Give Claude DeFi-grade risk awareness.
\n\n An MCP server that synthesizes DeFi risk across audits, exploits, oracle dependencies, composability, MEV, and slippage — exposed as tools any Claude Desktop / Cursor / Cline agent can call.\n
\n\n What you get ·\n Quick start ·\n Tools ·\n Project setup ·\n Full install guide ·\n PRD\n
\n\n---\n\n## What you get\n\nDoing real risk analysis on a DeFi position normally means bouncing between DefiLlama, Etherscan, Code4rena audits, Snapshot governance, the Rekt exploit feed, and your wallet — then stitching the picture together in your head.\n\nWith `defi-risk-mcp` installed, you ask Claude one question. It calls the six risk tools, deduplicates the exploit feed, ranks oracle dependencies, checks audit posture, and gives back a synthesis you can act on — **without ever signing a transaction or surrendering a key**.\n\n| Without it | With it |\n|---|---|\n| 8 browser tabs and a spreadsheet | One question in Claude |\n| \"I think the audits look fine?\" | Named audit firms, dates, scope, and exploit chain |\n| Yields ranked by APY only | Yields ranked by risk floor — APY is secondary |\n| Sign first, find out later | Decode + simulate before you sign |\n\n**Concrete use cases:**\n\n- _\"Is this $10K position on Aave actually safe?\"_ → 6-dimension risk synthesis (protocol, oracle, chain, asset, position, governance).\n- _\"What stablecoin yield can I find above 8% APY with TVL over $50M?\"_ → ranked by safety, with risk-floor next to each pool.\n- _\"Decode this transaction and tell me if it's safe to sign.\"_ → catches drain patterns, stale deadlines, burn-shaped recipients.\n- _\"What protocols got hit last month?\"_ → recent exploit feed across Rekt + BlockSec, deduped and ranked.\n\n---\n\n## Demo\n\n**Prompt:** _\"I'm thinking of supplying 10,000 USDC to Aave on Base. What are the risks?\"_\n\nClaude calls `get_position_risk` + `explain_protocol_risk` + `get_recent_exploits` + `get_chain_info` and synthesizes — verbatim from a live Claude Code session on Linux:\n\n> ### Risks of supplying 10,000 USDC to Aave v3 on Base\n>\n> **Protocol risk — LOW**\n> - Audits: 5 reputable firms on record — OpenZeppelin (2022), Trail of Bits (2022), Certora (formal verification, ongoing), SigmaPrime (2023, GHO/v3.1), Code4rena (2022).\n> - Exploit history: 1 historical incident (2022 CRV short attack) — and that was on Aave v2, not v3 — protocol contracts weren't exploited; it was a bad-debt event from an oracle-priced asset that was subsequently frozen. v3 has a clean record.\n> - TVL: ~$14.9B — deep enough that supply/withdraw liquidity is rarely a problem for a $10K position.\n> - Recent Base exploits (90 days): feed returned 0 real incidents.\n>\n> **Oracle risk — MEDIUM** (structural, not Aave-specific)\n> - Aave v3 reads Chainlink for all collateral pricing. A USDC supply position itself isn't directly priced (USDC is the unit of account), but Chainlink failure or stale prices can cause cascading bad-debt that hits the reserve where you're supplying. This is the single biggest non-headline risk.\n>\n> **Chain risk (Base) — MEDIUM**\n> - Sequencer: Base runs a centralized Coinbase sequencer. Outage → no withdrawals or liquidations until restored. A long sequencer halt during a USDC depeg event is the worst case.\n> - Bridge: USDC on Base is native (Circle's CCTP), not a bridge wrapper, so this risk is lower than on chains using lock/mint bridges. Withdrawing back to Ethereum still routes through the standard L2 → L1 7-day exit window if you bypass CCTP.\n>\n> **Asset risk (USDC) — LOW-MEDIUM**\n> - Circle freeze: USDC is freezable at the issuer level. Sanctioned addresses can lose funds outright. Not a behavioral risk for a normal user but worth noting.\n> - Depeg: March 2023 SVB depeg saw USDC trade ~$0.87 briefly. Aave v3 handled this correctly, but it's the historical worst case.\n>\n> **Position-specific risk — LOW**\n> - Utilization spike: if borrow demand spikes, withdraws can queue until utilization drops. For $10K on a multi-billion-dollar reserve, this is a non-issue 99% of the time.\n> - Variable APY: yield is not fixed — can drop quickly if borrow demand softens.\n> - `aBasUSDC` is rebasing (interest accrues to balance). Some downstream protocols don't accept it.\n>\n> **Governance risk — LOW**\n>\n> Recent Aave DAO activity is routine: risk-provider renewal, bug bounty restructure, AAVE buyback pause. No emergency or contentious proposals affecting USDC reserves.\n>\n> **Bottom line**\n>\n> For passive USDC supply, this is one of the lower-risk yields in DeFi. Three things to actually watch:\n> 1. Chainlink USDC/USD feed health (oracle is the real systemic risk)\n> 2. Base sequencer status during any USDC depeg\n> 3. Reserve utilization before sizing up — at $10K it's irrelevant.\n\nThe full verification log — including prompt #2 (yield discovery → Pendle APXUSD picked correctly) and prompt #3 (caught a drain-pattern transaction with burn-shaped recipient + stale deadline) — lives in [issue #5](https://github.com/Alike001/defi-risk-mcp/issues/5) and [issue #9](https://github.com/Alike001/defi-risk-mcp/issues/9).\n\n> 📹 90-second demo video: _coming soon_ \n\n---\n\n## Quick start\n\nThe MCP server is installed by registering it as a tool server in your MCP-compliant client (Claude Desktop, Cursor, Cline, Continue, Windsurf). It speaks JSON-RPC over stdio — your client spawns it and routes tool calls to it.\n\n**Step 1 — install:**\n\n```bash\nnpx -y -p @alike001/defi-risk-mcp defi-risk-mcp-install\n```\n\nThis writes a `defi-risk` entry into your Claude Desktop config (creating the file if it does not exist), preserving every other MCP server you already have. If a `defi-risk` entry is already present, the script asks before overwriting; pass `--force` to skip the prompt.\n\n**Step 2 — fully restart Claude Desktop** with `Cmd+Q` (macOS) / `Ctrl+Q` (Linux/Win). Closing the window is not enough — the server only respawns on a full quit.\n\n**Step 3 — verify** by typing `/mcp` in Claude. You should see `defi-risk` listed as ✔ connected with 6 tools. Then ask:\n\n> _\"What are the risks of supplying 10,000 USDC to Aave on Base?\"_\n\nIf Claude calls `get_position_risk`, `explain_protocol_risk`, and `get_recent_exploits`, you're set up. That whole flow takes about 30 seconds end-to-end on a fresh install.\n\nAPI keys are **optional at install time** — the server still comes up healthy without them, but the tools that need a specific key return a structured \"missing credentials\" error instead of crashing. See [Project setup → Required env keys](#required-env-keys) for which key unlocks which tool.\n\n### Manual install\n\nIf you prefer to edit the config yourself, paste this block into `claude_desktop_config.json` and restart Claude Desktop fully (Cmd/Ctrl-Q):\n\n```json\n{\n \"mcpServers\": {\n \"defi-risk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"-p\", \"@alike001/defi-risk-mcp\", \"defi-risk-mcp\"],\n \"env\": {\n \"ALCHEMY_API_KEY\": \"\",\n \"ETHERSCAN_API_KEY\": \"\",\n \"TENDERLY_USER\": \"\",\n \"TENDERLY_PROJECT\": \"\",\n \"TENDERLY_ACCESS_KEY\": \"\",\n \"INDEX_NETWORK_KEY\": \"\",\n \"BRAVE_SEARCH_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nConfig file paths:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nThe full guide — including Cursor and Cline paths, troubleshooting, and verification prompts — lives at [`docs/INSTALL.md`](docs/INSTALL.md). A copy-pasteable starting config is at [`claude-desktop-config-example.json`](claude-desktop-config-example.json).\n\n> **Read-only / simulate-only.** This MCP never signs transactions, never holds keys, never broadcasts. Per [ADR-003](research/encode-defi-mini-hack/docs/architecture.md#adr-003-read-only--simulation-only--no-signing) you always sign in your own wallet.\n\n---\n\n## Tools\n\n| # | Tool | What it does |\n|---|---|---|\n| 1 | `health_check` | Liveness probe — round-trips through stdio so clients can confirm the server is up before calling tools. |\n| 2 | `get_position_risk` | Synthesize risk for a known DeFi position across 6 dimensions (oracle, audit, exploit, counterparty, composability, MEV/slippage). |\n| 3 | `simulate_tx_risk` | Decode + simulate a raw tx against Tenderly; surface MEV / slippage / counterparty / oracle dependencies before you sign. |\n| 4 | `explain_protocol_risk` | Audit history + exploit chain + governance posture for a protocol (Aave, Lido, Compound, …). |\n| 5 | `get_recent_exploits` | Synthesized exploit feed across Rekt + BlockSec, deduped and ranked by recency and severity. |\n| 6 | `discover_yields_by_intent` | Post a yield-discovery intent to Index Network (with DefiLlama fallback per ADR-006); rank by risk. |\n| 7 | `find_safer_alternatives` | _Stretch_ — lower-risk replacements for a current position. Roadmap. |\n| 8 | `check_oracle_dependencies` | _Stretch_ — oracle dependency graph for a position or protocol. Roadmap. |\n\nTools that need credentials but don't have them return a structured `missing_credentials` error rather than crashing — the server still comes up \"connected\" in your client. Add the missing key to the `env` block and fully restart.\n\n---\n\n## What's missing (honest)\n\nThis MCP is shipped for the [Encode DeFi Mini Hack 2026](https://www.encodeclub.com/programmes/defi-mini-hack) under a tight time box. The following are explicitly deferred:\n\n- **Token-emission quality scoring** (real-yield vs. inflationary) — roadmap; cuttable per PRD scope.\n- **Governance-proposal translator** — roadmap; cuttable per PRD scope.\n- **Live wallet inference** (`portfolio_after`) — roadmap.\n- **`find_safer_alternatives` and `check_oracle_dependencies`** — listed in the tool table as stretch; not yet implemented in this build.\n- **Index Network full intent flow** — runs through the SDK→CLI→Brave→DefiLlama fallback router (ADR-006); end-to-end intent matching is gated on the SDK reaching parity with the published spec.\n- **Multi-chain coverage beyond Ethereum + Base + Arbitrum** — bounded by the free-tier RPC budget.\n\nIf a tool you need is missing, open an issue — the architecture is built so adding a tool is one file in `src/tools/` plus one registration in `src/index.ts`.\n\n---\n\n## Project setup (local dev)\n\nFor contributors, or if you want to run the server from source instead of from npm.\n\n```bash\ngit clone https://github.com/Alike001/defi-risk-mcp.git\ncd defi-risk-mcp\npnpm install\ncp .env.example .env # then fill in the keys you need — see table below\npnpm test # full vitest suite (136 tests)\npnpm exec tsc --noEmit # type-check\npnpm run lint # biome\npnpm run build # writes dist/\nnode dist/index.js # smoke-test the MCP server over stdio (Ctrl-C to exit)\n```\n\nTo wire your local build into Claude Desktop, point the `command` at `node` and the `args` at your absolute `dist/index.js` path in `claude_desktop_config.json` — no `npx` needed.\n\n### Required env keys\n\nEvery key is optional at boot; missing keys just disable specific tools.\n\n| Key | Required for | Where to get it |\n|---|---|---|\n| `ALCHEMY_API_KEY` | On-chain reads — Ethereum, Base, Arbitrum | [alchemy.com](https://www.alchemy.com) — free tier |\n| `ETHERSCAN_API_KEY` | Contract source code + verification status | [etherscan.io/myapikey](https://etherscan.io/myapikey) — free |\n| `TENDERLY_USER` + `TENDERLY_PROJECT` + `TENDERLY_ACCESS_KEY` | `simulate_tx_risk` — drain-pattern detection | [tenderly.co](https://tenderly.co) — free tier |\n| `INDEX_NETWORK_KEY` | `discover_yields_by_intent` — intent matching | `npm i -g @indexnetwork/cli && index login` — bearer in `~/.index/credentials.json` |\n| `BRAVE_SEARCH_API_KEY` | Web-search fallback when Index is unavailable | [api.search.brave.com](https://api.search.brave.com) — free tier |\n\nWithout any of these, `discover_yields_by_intent` still works — it falls back to the public DefiLlama Yields API (no key required) and reports `discovery_source: \"fallback\"` in the response so the agent can be honest about provenance (ADR-006).\n\n### Dev gates this repo enforces\n\n- **BDD-tested PRs** — every story under `research/encode-defi-mini-hack/docs/stories/*.md` lists Given/When/Then acceptance criteria; tests come first.\n- **§14 anti-slop gate** — no mock / fake / dummy data in the hot path (see [`CLAUDE.md`](CLAUDE.md)).\n- **Branch protection** — CI required, no force pushes to `main`.\n\n### Publishing (maintainers only)\n\n`prepublishOnly` runs `pnpm build`. From a clean working tree:\n\n```bash\npnpm publish --dry-run --access public # preview the tarball — always run first\nnpm login && pnpm publish --access public # real publish (requires npm 2FA code)\n```\n\nAfter a publish, bump the version with `npm version patch|minor|major`, update [`CHANGELOG.md`](CHANGELOG.md), and `git push --follow-tags`.\n\nThe `bin` field exposes both:\n\n- `defi-risk-mcp` — the MCP server entrypoint (what Claude Desktop spawns).\n- `defi-risk-mcp-install` — the install helper that merges the canonical entry into Claude Desktop config without overwriting other servers.\n\n---\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n\n---\n\nBuilt for Encode DeFi Mini Hack 2026 — [encodeclub.com/programmes/defi-mini-hack](https://www.encodeclub.com/programmes/defi-mini-hack).\n","readmeFilename":"README.md"}