graph-aave-mcp
<div align="center">
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.
</div>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
{
"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