defi-yield-mcp

An MCP server for querying DeFi yield pool data and (eventually) risk signals — built for anyone deciding where idle funds should earn yield, without having to manually cross-reference DefiLlama, protocol docs, and exploit trackers.

Why this exists

DefiLlama has the raw data but no MCP server exposing it in agent-friendly form with any risk framing layered on.

Setup

pip install -r requirements.txt
python server.py

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "defi-yield": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

No API key required — DefiLlama's public endpoints are used as-is.

Tools — implemented

get_pool_risk_score and get_protocol_audit_status are only populated for protocols in CURATED_PROTOCOL_DATA in server.py (currently: aave-v3, compound-v3, morpho-blue, curve-dex, makerdao). Anything else returns an honest "not in dataset" response rather than a fabricated score.

Data sources

• DefiLlama Yields API (yields.llama.fi/pools) — APY, TVL, pool metadata. Free, no key, refreshes ~hourly. Responses are cached in-process for 5 minutes to avoid redundant calls.

• DefiLlama hacks dataset (api.llama.fi/hacks) — historical exploit records.

Risk scoring methodology (implemented)

This is deliberately not a single blended score. For a payments protocol holding funds earmarked for payees, some failures shouldn't be averaged away by a good number elsewhere — so the design is gate-then-score:

Hard gates (fail either → pool is excluded, no score computed):

1. Audit gate — protocol must have ≥ 2 audits from recognized firms and be live ≥ 12 months (MIN_AUDIT_COUNT, MIN_PROTOCOL_AGE_DAYS in server.py).

2. Liquidity gate — protocol category must support instant withdrawal (lending markets, savings-style primitives, stable AMMs — not locked farms), and the specific pool's TVL must be ≥ 20x the assumed position size (MIN_TVL_DEPTH_MULTIPLE), so an exit doesn't move the market.

Secondary score (only computed if both gates pass):

• Yield stability — coefficient of variation of daily APY over the trailing 30 days, converted to a 0–100 score (lower variance → higher score).

• TVL stability — same calculation applied to daily TVL.

• These are averaged into a composite_stability_score. Note this ranks steadiness, not size — a steady 4% outranks a volatile 9% by design.

The curated dataset and thresholds are plain module-level constants in server.py, not hidden in a black box — adjust MIN_AUDIT_COUNT, MIN_PROTOCOL_AGE_DAYS, or MIN_TVL_DEPTH_MULTIPLE to fit a different risk appetite.

Extending the curated dataset

To add a protocol, add an entry to CURATED_PROTOCOL_DATA in server.py with audits, audit_count, live_since, bug_bounty, category, and instant_liquidity, sourced from the protocol's own docs/GitHub. There's no public API for audit status across protocols, so this stays hand-maintained by design — a fabricated automated score would be worse than an honest gap.

Testing

Offline (no network needed):

pip install "mcp[cli]" httpx
python test_offline.py

Runs all six tools against realistic mock fixtures (patched in place of the real HTTP calls) so you can see the gate-then-score logic execute end to end — including one fixture deliberately sized to fail the liquidity gate, and one protocol deliberately left out of the curated dataset, so you can see both failure paths behave correctly, not just the happy path.

Live (hits the real DefiLlama API):

pip install "mcp[cli]" httpx
python server.py

Then connect via an MCP client (see Setup above) and call the tools directly, or add a small if __name__ == "__main__": block calling the async functions with asyncio.run(...) the same way test_offline.py does, minus the monkeypatch. Worth checking the live /pools and /chart/{pool} response shapes against what's assumed in server.py the first time you run it — those field names were reconstructed from documentation, not verified live.

Known limitations

• _looks_locked is a keyword heuristic, not a guarantee. It catches obvious cases (a poolMeta or symbol containing "stake", "umbrella", "vault", "lock", etc. — added after live testing surfaced an Aave "Umbrella" staking pool passing the liquidity gate incorrectly) but a new locked product with unrelated naming could still slip through the protocol-level instant_liquidity flag. Treat gate_status: passed as a strong signal, not a certainty — check the pool_meta field in the response yourself for anything unfamiliar.

• No risk scoring for protocols outside CURATED_PROTOCOL_DATA — those correctly come back gate_status: unknown rather than a fabricated score.

• Exploit history depends on DefiLlama's dataset being current; cross-check anything decision-relevant against the protocol's own disclosures.

• Not audited or battle-tested — this is a portfolio/reference project, not a production risk tool. Don't make real allocation decisions off get_pool_apy alone.