graph-aave-mcp

MCP server for AAVE V2, V3, and V4 — 51 tools across 17 Graph subgraphs + the Aave V4 API + V4 Omnigraph (for data the REST API doesn't expose).

Covers lending markets, user positions, health factors, cross-chain liquidation risk monitoring, liquidations, flash loans, governance, V4 hubs/spokes, exchange rates, swap quotes, rewards, and protocol history.

Published to the MCP Registry as io.github.PaulieB14/graph-aave-mcp

Three Data Sources

Quick Start

# Claude Code
claude mcp add graph-aave -- npx -y graph-aave-mcp

# Set Graph API key for subgraph tools (V4 tools work without it)
export GRAPH_API_KEY=your-key-here

# Optional but recommended: the two live on-chain tools read via RPC, and the
# unconfigured public fallback is rate-limited or blocked on many networks.
export ETHEREUM_RPC_URL=https://your-endpoint

{
  "mcpServers": {
    "graph-aave": {
      "command": "npx",
      "args": ["-y", "graph-aave-mcp"],
      "env": {
        "GRAPH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Free Graph API key: thegraph.com/studio (100K queries/month free tier).

Hosted deployment (no install): Fronteir AI

V2/V3 Tools (The Graph Subgraphs)

15 tools + 1 raw query escape hatch. Requires GRAPH_API_KEY.

Response size. get_aave_reserves returns every active reserve by default — on Ethereum that is 67 reserves, ~28k tokens. Pass symbols: ["USDC"] for one asset (~675 tokens), compact: true for rates only, or limit to cap the rows. get_v4_reserves takes the same three options.

Discovery

Lending Markets

User Positions

Protocol Events

Governance

Advanced

Supported Chains (V2/V3)

Liquidation Risk Tools (NEW)

8 tools powered by dedicated risk subgraphs across 5 chains. Requires GRAPH_API_KEY.

Real-time liquidation risk monitoring with health factors, risk scores (0–100), risk level classifications (safe/warning/danger/critical), and cross-chain risk summaries.

Risk Monitoring

Risk Events

Discovery

Supported Chains (Liquidation Risk)

V4 Tools (Aave API)

17 tools powered by api.v4.aave.com/graphql. No API key needed. (api.aave.com/graphql is an alias for the same schema; override either with AAVE_V4_API_URL.)

Note: the V4 Omnigraph tools (next section) cover gaps the REST API doesn't expose and require GRAPH_API_KEY. The 16 tools listed below remain key-free.

Liquidity Model

User Data

V4 Omnigraph Tools (subgraph — fills gaps the Aave API doesn't expose)

5 tools powered by the aave-v-4 subgraph (QmcKrCRSPrMABEfQjyPF6DqhbY7zzcEj6h5QxQmKLcHFSs). Requires GRAPH_API_KEY (the same free key used by V2/V3 subgraph tools).

These cover what api.aave.com/graphql structurally can't return: Hub↔Spoke flow events, per-user risk-premium trajectories, liquidation post-mortems with full premium-delta context, treasury/fee/deficit accounting, and governance-trail snapshots.

V4 Architecture

Hubs (Core, Plus, Prime)
  └── Assets (WETH, USDC, GHO, cbBTC, etc.)
       └── Spokes (Main, Bluechip, Kelp, Lido, Ethena, ...)
            └── Reserves (per-spoke lending markets)
                 └── User Positions (health factor, collateral, debt)

V4 enables cross-chain lending: supply on one spoke, borrow on another. Hubs aggregate liquidity across spokes.

Guided Prompts

7 pre-built workflows that guide agents through multi-step analysis:

Example Questions

Liquidation Risk (new):

• "Which Aave positions on Arbitrum are closest to liquidation?"
• "Give me a cross-chain risk dashboard — which network has the most at-risk positions?"
• "Is wallet 0x... at risk of liquidation on any chain?"
• "Show me recent risk alerts — which positions just became critical?"
• "How has this wallet's health factor changed over time on Base?"

V4:

• "What are the Aave V4 hubs and their utilization?"
• "Show me V4 reserves with the highest supply APY"
• "What's the current ETH price on Aave V4?"
• "Compare V3 vs V4 USDC supply rates"
• "What spokes does Aave V4 have on Ethereum?"

V2/V3:

• "What are the top AAVE markets on Ethereum by TVL?"
• "Compare WETH borrow rates across all V3 chains"
• "Analyze the AAVE position for wallet 0x..."
• "If ETH drops 30%, will address 0x... get liquidated?"
• "Show me the last 20 liquidations on Ethereum"
• "What AAVE governance proposals are active?"

Development

git clone https://github.com/PaulieB14/graph-aave-mcp.git
cd graph-aave-mcp
npm install
npm run build
GRAPH_API_KEY=your-key node build/index.js

Tests

npm test                                     # V4 tools only
GRAPH_API_KEY=... ETHEREUM_RPC_URL=... npm test   # everything

test/smoke.mjs starts the server over stdio and calls every registered tool, failing if any returns an error or an unexpectedly empty collection. Tools whose backend is unavailable in the current environment (no Graph key, no reachable RPC) are skipped rather than failed, so the suite is meaningful without credentials and thorough with them.

It exists because get_v4_hub_flows shipped pointing at an undeployed subgraph and nobody noticed: Graph Studio answers a missing subgraph with HTTP 200 and {"message":"Not found"}, the client only checked for a GraphQL errors key, and the tool returned flows: [] — indistinguishable from "no activity on chain". Every backend call now fails loudly instead.

Environment variables

License

MIT