curator-mcp

Live DeFi lending yields, TVL, utilization and token prices on Base — as MCP tools.

An MCP server that answers the questions an agent actually asks about DeFi markets: where should this asset sit, what does it earn, and how deep is the liquidity? Data comes from The Graph — Messari standardized subgraphs for lending and DEX markets, and the Token API for spot prices.

Standalone and dependency-light. It knows nothing about any particular agent; it was extracted from one, which is the only relationship it has to the vault curator that first used it.

Install

Requires Python ≥ 3.10 and a free Graph API key from thegraph.com/studio → API Keys.

From a clone — works today:

git clone <this-repo> && cd <this-repo>
uv pip install ./data/curator_mcp

The two sibling packages (curator-data, curator-schema) resolve from the repo automatically.

From PyPI — once published (see PUBLISHING.md; the packages are built and verified, the upload needs a token):

uvx curator-mcp                  # run without installing

Configure your MCP client

{
  "mcpServers": {
    "curator": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/repo", "curator-mcp"],
      "env": { "GRAPH_API_KEY": "your-key-here" }
    }
  }
}

Once published, that becomes simply "command": "uvx", "args": ["curator-mcp"].

Either way, Claude Desktop, Claude Code, Cursor, Zed and anything else speaking MCP over stdio will pick the tools up.

Tools

Plus a curator://protocols resource listing which protocols are configured.

Response shape

Every tool returns the same three guarantees:

{
  "asset": "USDC",
  "protocols": [
    {
      "protocol": "aave-v3",
      "supply_apy": 0.0432,        // fraction — use this for arithmetic
      "supply_apy_pct": 4.32,      // percent  — use this for display
      "tvl_usd": 84200000.0,
      "utilization": 0.91,
      "fact_ids": ["messari:yield:aave-v3/usdc", "messari:tvl:aave-v3/usdc"],
      "sources": ["messari"]
    }
  ],
  "best_apy": "aave-v3",
  "deepest_tvl": "moonwell",
  "taken_at": "2026-07-25T14:05:00+00:00",
  "errors": []                     // non-empty means your view is PARTIAL
}

1. fact_ids and sources on every number. Provenance travels with the data, so a model can cite what it saw and a human can check it.
2. errors on every response. If a protocol could not be reached it is named here. A non-empty errors means the answer is partial and should be described that way — never silently treated as the whole market.
3. APY twice, in both units. supply_apy is a fraction (0.0432); supply_apy_pct is a percentage (4.32). Mixing them up is a 100× error, so neither has to be inferred.

See SKILL.md for how an agent should use these tools well.

Configuration

Values are read from the environment, or from a .env found by walking up from the package.

Extending it

Protocols are configuration, not code. Because Messari publishes one standardized schema per protocol type, every lending market answers the same GraphQL query — so adding one is a single line in curator_data/sources/protocols.py:

Protocol(key="moonwell", subgraph_id="33ex…sBrg", family="lending", label="Moonwell (Base)"),

Adding a whole new provider (Chainlink, Pyth, DefiLlama) is one file plus one registration line — see the curator-data README. New sources appear in these tools automatically, because tools resolve sources by capability (provides = ("price",)) rather than by name.

Verify it works

GRAPH_API_KEY=… curator-data verify-live      # live gateway check, names any failing protocol
uv run pytest data/tests -q                   # offline test suite

License

MIT.