Aave MCP

The official Model Context Protocol server for Aave. Connect any AI assistant to Aave and let it read live protocol data and build non-custodial transactions across both Aave V3 and V4 through one endpoint.

Ask your assistant "what's my health factor?", "where's the best stablecoin yield?", or "prepare a supply of 500 USDC" and it calls Aave directly, with numbers that match the app.

Why this server

• V3 and V4, one endpoint. Most tools take a version argument (v3, v4, or all), so a single connection answers questions about either protocol, or compares them.
• Authoritative. It wraps the official @aave/client SDK, so results match app.aave.com (V3) and pro.aave.com (V4), including V4-specific concepts like hub/spoke, risk premium, and the correct health factor. Third-party tools that reimplement the math get V4 wrong.
• Non-custodial by design. Read and prepare_* tools return data or an unsigned transaction / EIP-712 payload. The user's wallet signs; this server never holds keys and never submits for you.
• Built for LLMs. Responses are compact and predictable ({ data, next_actions }, typed structuredContent), so the model spends its budget on your problem, not on parsing. Reserve detail is projected down from ~17 KB of raw SDK payload to ~1 KB, and get_markets takes a symbols filter so asking about one asset does not return all ~70 reserves on the chain.
• Errors an agent can act on. When Aave rejects an input, the reason comes back verbatim and marked non-retryable, so the model fixes its arguments instead of looping on a generic failure.

Connect your MCP client

The server speaks streamable HTTP, so any MCP client connects with just the URL. Production is https://mcp.aave.com; for local dev use http://localhost:8787.

• Claude Code: claude mcp add --transport http aave https://mcp.aave.com
• Claude Desktop / claude.ai: Settings → Connectors → Add custom connector → https://mcp.aave.com
• ChatGPT: Settings → Connectors (developer mode) → add MCP server → https://mcp.aave.com
• Cursor: ~/.cursor/mcp.json → { "mcpServers": { "aave": { "url": "https://mcp.aave.com" } } }
• VS Code (Copilot): code --add-mcp '{"name":"aave","type":"http","url":"https://mcp.aave.com"}'
• Windsurf: Settings → MCP → Add server → https://mcp.aave.com
• Codex CLI: ~/.codex/config.toml → [mcp_servers.aave] with url = "https://mcp.aave.com"
• Other (Cline, LM Studio, Goose, …): add a remote streamable-HTTP MCP server at https://mcp.aave.com

What you can ask

Once connected, try:

• "What's the health factor of 0x… on Aave V4, and how close is it to liquidation?"
• "Which has the higher USDC supply APY right now, Aave V3 or V4 on Ethereum?"
• "Show the USDC supply APY trend over the last month on V4."
• "What are 0x…'s positions and net APY across Aave?"
• "Prepare a transaction to supply 500 USDC to Aave V4 for 0x…, and show the resulting health factor first."
• "What's my recent Aave activity?"
• "Which Aave governance proposals are open for voting, and has each one met quorum?"
• "Who were the biggest voters on proposal 500, and did 0x… vote?"

The server answers with live data and, for actions, hands back an unsigned transaction for the user to sign in their own wallet.

Tools

Reads take version (v3 | v4 | all). Amounts are in main units (e.g. 10.5), never wei. Every rate and percentage is a percent, named with a Pct suffix and rounded to 4 dp, on both versions: "3.32" means 3.32%. Plain ratios (health factor) stay as-is.

| Tool | What it does | |---|---| | get_chains | Chains Aave supports on a version | | get_markets | Markets / reserves (symbol, APY, caps) for a chain; symbols filters to the assets you want | | get_reserve_details | Deep detail for a single reserve (rates, caps, risk params) | | get_apy_history | Supply or borrow APY time-series over a window | | get_protocol_history | Protocol-wide deposits and borrows over a window (v4) | | get_user_summary_history | One wallet's net balance, supplied, borrows and health factor over a window (v4) | | get_hubs / get_hub_assets | Hub-level liquidity and accounting, as opposed to the per-spoke view get_markets gives (v4) | | get_user_positions | A wallet's supplies / borrows (+ per-position health on v4); carries the spokeId | | get_position_items | The individual supplies or borrows inside one v4 spoke, each with a positionItemId | | get_user_summary | Aggregate position and health factor | | get_user_activity | Transaction history (supply/borrow/repay/…), paginated | | get_user_rewards | Claimable rewards across every supported chain, Merit programmes included; on v3 the response also carries the claim transaction | | preview_action | Simulate supply/borrow/withdraw/repay and see the resulting health factor (v4) | | prepare_action | Build an unsigned supply/borrow/withdraw/repay transaction | | prepare_set_collateral | Build an unsigned enable/disable-collateral transaction | | prepare_set_emode | Switch a wallet's v3 eMode category (get_markets returns the categories) | | prepare_liquidation | Build an unsigned liquidation of a position whose health factor is under 1 | | get_transaction_processed | Whether Aave has observed a transaction yet; poll this instead of sleeping before a dependent action | | prepare_claim_rewards | Build an unsigned rewards-claim transaction | | get_swappable_tokens | The chains and tokens a swap can be quoted on | | get_swap_quote | Quote a token swap (protocol-agnostic, runs on the v4 backend); slippagePct caps slippage | | prepare_order | What the user signs for a quoted order: EIP-712 typed data, or the on-chain transaction for a native-token sell | | submit_signed_order | Relay a user-signed order | | prepare_cancel_order / cancel_order | The cancellation to sign, and the relay (or on-chain cancel transaction) | | get_order_status / get_pending_orders | Check one order, or list a wallet's orders across chains | | get_sgho_vault | Savings GHO vault state and a wallet's position: target rate, supply cap, maxDeposit / maxWithdraw (v3, Ethereum) | | get_sgho_preview | Convert between GHO and sGHO shares at the current vault index | | prepare_sgho_action | Build an unsigned sGHO deposit or withdrawal; a withdrawal is denominated in shares, not GHO | | prepare_stkgho_migrate | Build an unsigned migration of an entire stkGHO position into sGHO | | get_aave_guide | On-demand protocol + usage guidance for the model |

Aave DAO governance

These take no version: Governance V3 is the DAO's own contract generation, unrelated to the v3 / v4 markets. Vote tallies, quorum and per-voter power are all in AAVE, so they compare directly.

| Tool | What it does | |---|---| | search_governance_proposals | List proposals by lifecycle state (active, queued, executed, …), or full-text search them | | get_governance_proposal | One proposal in full, with quorumMet / differentialMet (the two conditions it must meet to pass) | | get_proposal_votes | Who voted and with how much power, largest first, plus totals across every vote | | get_user_vote | How one wallet voted on one proposal; voted: false when it did not | | get_proposal_payloads | What a proposal executes, per target chain, and whether it has landed everywhere yet |

Prompts and resources

Clients that surface MCP prompts get one-click workflows: check_health, best_stablecoin_yield, prepare_supply, review_position. Each guide topic is also exposed as a resource at aave://guide/<topic>, and prompt arguments support completion.

Non-custodial and safe

• Read and prepare_* tools are side-effect-free; prepare_* returns an unsigned TransactionRequest (or an Erc20ApprovalRequired step, or EIP-712 typed data for orders).
• The state-changing tools, submit_signed_order and cancel_order, relay an order or cancellation the user already signed.
• The server stores no private keys and cannot move funds. Signing always happens in the user's wallet.
• Position swaps, repay-with-supply and leverage are built but not served: their adapter contracts are awaiting a second security audit. The tools are absent from tools/list and a call for one is refused, so the gate covers the action and not just the listing. Search AUDIT-GATED to serve them again.

How it works

One Cloudflare Worker served at the root (mcp.aave.com), speaking MCP over streamable HTTP (protocol 2025-06-18, with 2025-03-26 accepted for older clients). It wraps two versions of the official SDK in a single bundle: @aave/client (V4) and @aave/client-v3 (V3, via an npm alias). A version argument dispatches per protocol, and version: "all" fetches both concurrently. Read responses are projected to the fields a model needs and carry next_actions hints so the agent knows the next step.

Governance data comes from the DAO's own indexer rather than the market SDKs, over the same API app.aave.com/governance/v3 reads from. GOVERNANCE_API_URL overrides the endpoint for staging.

POST / is the MCP endpoint (/mcp is an alias). GET there returns 405, as the spec requires of a server that offers no SSE stream; the human-readable status page lives at GET /health.

Develop

Requires Node 22 (for wrangler).

nvm use 22
pnpm install       # first time
pnpm dev           # wrangler dev on http://localhost:8787
pnpm typecheck     # tsc --noEmit, for src/test and for eval
pnpm test          # vitest: protocol surface + argument validation, no network
pnpm build         # wrangler dry-run: bundle + validate

CI runs all three on every push and pull request.

Those three cover the server. What they cannot see is whether an agent can use it: a tool with a confusing name or an ambiguous description still returns correct data, so every test above passes while the agent muddles through. That is what eval/ measures, with DeepEval's three MCP metrics over recorded agent traces, ground truth pulled straight from @aave/client, and an eth_call of every transaction the server builds, so one that reverts on chain stops reading as a pass.

python3 -m venv .venv && .venv/bin/pip install -r eval/score/requirements.txt   # first time
export OPENROUTER_API_KEY=sk-or-...   # or ANTHROPIC_API_KEY; one key drives the agent and the judges
pnpm eval          # drive the agent, write a trace
pnpm eval:score    # judge the trace: tool choice, argument quality, task completion
pnpm eval:gate     # compare against eval/baseline.json

It runs on pull requests to main, comments the results, and blocks on a regression against the committed baseline. See eval/README.md, which covers how to take a score drop back to the tool name or description that caused it.

The governance tools use typed GraphQL documents generated from the live schema. The generated output is committed, so nothing above touches the network. Run pnpm codegen after editing src/governance/operations.ts, and commit the result; it is also how an upstream schema change surfaces, either as a codegen failure on a field that no longer exists or as a diff in src/governance/gql/.

Point an MCP client at http://localhost:8787/, or POST JSON-RPC directly:

curl -s -X POST http://localhost:8787/ -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_user_summary","arguments":{"user":"0x...","version":"v4"}}}'

What is recorded

Calls are counted for product analytics: tool name, MCP method, protocol version, chain id, and the client name and version from the handshake. A call that names a wallet is counted under an HMAC of that wallet, so the address itself is never recorded, and any address appearing in an error message is redacted before delivery. No keys, signatures, transaction content or prompt text are collected, and the server sends no IP address. See the privacy policy.

Deploy and publish

Deployment (Cloudflare Workers + the mcp.aave.com custom domain) and registry publishing (@aave/mcp on npm and com.aave/mcp in the MCP Registry) are documented in DEPLOY.md. The protocol layer is the official @modelcontextprotocol/sdk; usage analytics go to Amplitude via @amplitude/mcp-analytics when AMPLITUDE_API_KEY is set.

Roadmap

• Deploy to mcp.aave.com and publish to the MCP registry.
• OAuth 2.1 + rate limiting for a public launch (ALLOWED_ORIGINS tightens browser access today).
• Position swaps, repay-with-supply and leverage once the second audit clears.
• A read-only escape hatch for the long tail of queries.

License

Business Source License, see LICENSE. As a customized license, BUSL uses the LicenseRef- prefix per SPDX Spec v2.3, Annex E.