Aave MCP
Official Aave MCP for V3 and V4 markets, positions, governance, and transaction preparation.
Open source Repository Open in the app JSON README (API)
About
Official Aave MCP for V3 and V4 markets, positions, governance, and transaction preparation.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.aave
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Added
- 2026-09-02 17:00:56
- Updated
- 2026-09-13 03:08:55
- Origin id
com.aave/mcp
README
# Aave MCP
The official [Model Context Protocol](https://modelcontextprotocol.io) 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](https://workers.cloudflare.com) 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).
```sh
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.
```sh
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](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:
```sh
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](https://aave.com/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](DEPLOY.md). The protocol layer is the
official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk); usage
analytics go to Amplitude via
[`@amplitude/mcp-analytics`](https://github.com/amplitude/Amplitude-MCP-Analytics-Node) 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](LICENSE). As a customized license, BUSL uses the `LicenseRef-` prefix per [SPDX Spec v2.3, Annex E](https://spdx.github.io/spdx-spec/v2.3/using-SPDX-short-identifiers-in-source-files/).