Summary
Connects Claude to AAVE's decentralized lending protocol across V2, V3, and V4 deployments. Exposes 40 tools split across three data sources: The Graph subgraphs for V2/V3 historical data on 11 chains, dedicated liquidation risk subgraphs tracking health factors and position risk across 5 chains, and the official AAVE V4 API for hub/spoke liquidity models and cross-chain positions. Query lending markets, user collateral and debt positions, flash loans, liquidation events, governance proposals, and simulate health factor changes under different price scenarios. The V4 tools cover the new hub architecture, exchange rates via Chainlink oracles, and swap quotes through CoW Protocol. Requires a free Graph API key for subgraph access; V4 endpoints work without authentication.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
graph-aave-mcp
MCP server for AAVE V2, V3, and V4 — 50+ 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
| Source | Version | What it provides | Auth |
|---|---|---|---|
| The Graph subgraphs | V2/V3 | 11 subgraphs across 7 chains — reserves, positions, events, governance | GRAPH_API_KEY (free) |
| Liquidation Risk subgraphs | V3 | 5 chains — real-time health factors, risk scores, risk alerts, protocol risk stats | GRAPH_API_KEY (free) |
| Aave V4 API | V4 | Hubs, spokes, reserves, exchange rates, user positions, activities, swap quotes, rewards | None needed |
| V4 Omnigraph subgraph | V4 | Hub↔Spoke flow events, per-user risk-premium history, liquidation post-mortems, treasury/fee/deficit accounting, spoke config governance trail | GRAPH_API_KEY (free) |
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
Claude Desktop / Cursor config
{
"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.
Discovery
| Tool | Description |
|---|---|
list_aave_chains | All supported chains with subgraph IDs, versions, 30d query volumes |
get_aave_schema | Full GraphQL schema introspection for any chain |
Lending Markets
| Tool | Description |
|---|---|
get_aave_reserves | All active markets — TVL, supply/borrow APY, LTV, liquidation thresholds |
get_aave_reserve | Deep detail on one asset: lifetime stats, config, token addresses |
get_reserve_rate_history | Historical APY, utilization, TVL snapshots |
User Positions
| Tool | Description |
|---|---|
get_aave_user_position | Wallet's supplied/borrowed assets, collateral flags, e-mode |
simulate_health_factor | Simulate price changes on a user's health factor |
Protocol Events
| Tool | Description |
|---|---|
get_recent_borrows | Recent borrows — filter by user or asset |
get_recent_supplies | Recent supplies/deposits (auto-handles V2 vs V3 schema) |
get_aave_repays | Recent repayments |
get_aave_liquidations | Recent liquidations — filter by user or liquidator |
get_aave_flash_loans | Recent flash loans with fees |
Governance
| Tool | Description |
|---|---|
get_governance_proposals | Proposals with titles, states, vote counts |
get_proposal_votes | Per-voter breakdown by voting power |
Advanced
| Tool | Description |
|---|---|
query_aave_subgraph | Raw GraphQL — execute any query against any chain |
Supported Chains (V2/V3)
| Chain | Version | 30d Queries |
|---|---|---|
| Ethereum | V3 | 21.6M |
| Base | V3 | 5.6M |
| Arbitrum | V3 | 5.6M |
| Polygon | V3 | 2.0M |
| Optimism | V3 | 1.8M |
| Avalanche | V3 | 1.2M |
| Ethereum | V2 | 701K |
| Polygon | V2 | 216K |
| Avalanche | V2 | 133K |
| Fantom | V3 (Messari) | 13K |
| Ethereum | Governance V3 | 486K |
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
| Tool | Description |
|---|---|
get_at_risk_positions | Positions at risk of liquidation — filter by risk level, sorted by risk score |
get_user_risk_profile | Full risk profile for a wallet — all positions with health factors and risk scores |
get_protocol_risk_stats | Aggregate stats: total positions, danger/warning/critical counts |
get_cross_chain_risk_summary | Risk overview across all 5 chains in one call |
Risk Events
| Tool | Description |
|---|---|
get_risk_alerts | Risk level transitions — when positions move between safe/warning/danger/critical |
get_risk_liquidations | Liquidation events with collateral/debt assets, amounts, and tx hashes |
get_health_factor_history | Health factor trend over time for a specific wallet |
Discovery
| Tool | Description |
|---|---|
list_risk_chains | Available liquidation risk chains with subgraph IDs and query volumes |
Supported Chains (Liquidation Risk)
| Chain | 30d Queries | Signal |
|---|---|---|
| Ethereum | 21.1K | 20.2K GRT |
| Arbitrum | 19.3K | 35.7K GRT |
| Base | 16.2K | 15.2K GRT |
| Polygon | 13.2K | — |
| Optimism | 13.0K | — |
V4 Tools (Aave API)
16 tools powered by api.aave.com/graphql. No API key needed.
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
| Tool | Description |
|---|---|
get_v4_hubs | Liquidity hubs (Core, Plus, Prime) with TVL and utilization |
get_v4_spokes | Cross-chain spokes (Main, Bluechip, Kelp, Lido, Ethena, EtherFi, Forex, Gold, Lombard) |
get_v4_reserves | Per-spoke reserves with supply/borrow APYs, risk params, caps |
get_v4_chains | Supported V4 chains |
get_v4_asset | Cross-hub asset summary with average APYs and price |
get_v4_exchange_rate | Any token price via Chainlink oracles (ERC-20, native, or fiat) |
get_v4_asset_price_history | Historical token prices |
get_v4_protocol_history | Total deposits/borrows over time |
User Data
| Tool | Description |
|---|---|
get_v4_user_positions | Cross-chain positions — health factor, collateral, debt, borrowing power |
get_v4_user_summary | Aggregated portfolio: total positions, net balance, net APY |
get_v4_user_supplies | Supply positions with principal and interest |
get_v4_user_borrows | Borrow positions with debt breakdown |
get_v4_user_balances | Cross-chain token holdings with best APYs per token |
get_v4_user_activities | Transaction history: supplies, borrows, repays, liquidations, swaps |
get_v4_claimable_rewards | Claimable Merkl and points rewards |
get_v4_swap_quote | Read-only swap pricing via CoW Protocol (MEV-protected) |
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.
| Tool | Description |
|---|---|
get_v4_hub_flows | Hub↔Spoke routing events (Add, Remove, Draw, Restore, RefreshPremium, ReportDeficit, TransferShares) with AaveKit-joined spoke names and asset symbols |
get_v4_user_risk_trajectory | Per-user risk-premium snapshot history — every RefreshPremium event for a user, plus the latest premium and the spoke it was set on |
get_v4_liquidation_postmortem | Full liquidation event by tx hash or user — collateral/debt amounts, liquidator, premium-share / offset-ray / restored-premium deltas |
get_v4_treasury_flows | Merged stream of FeeMint / Sweep / Reclaim / DeficitEliminated events ordered by block desc, optionally filtered by hub (Core/Plus/Prime) and time window |
get_v4_spoke_config_history | Spoke liquidation-config governance trail — current and historical targetHealthFactor, healthFactorForMaxBonus, liquidationBonusFactor per spoke |
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:
| Prompt | Description |
|---|---|
analyze_aave_user | Full wallet analysis: positions, health factor, liquidation risk |
aave_chain_overview | Protocol overview: top markets, rates, recent activity |
compare_aave_rates | Compare APY for one asset across all chains |
aave_liquidation_analysis | Liquidation patterns, top liquidators, at-risk markets |
aave_governance_overview | Recent proposals, voting results, active decisions |
aave_full_stack_analysis | Cross-version comparison: V2 vs V3 vs V4 rates and positions |
cross_chain_risk_monitor | NEW — Cross-chain liquidation risk: riskiest positions, alerts, protocol health |
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
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
GRAPH_API_KEY*secretAPI key for The Graph network. Required to query subgraphs. Get one free at https://thegraph.com/studio/apikeys/