AAVE V2/V3 lending & governance MCP — 7 chains via The Graph subgraphs
This MCP server provides AAVE V2/V3 lending and governance data sourced from The Graph. It targets 7 chains via Graph subgraphs and is distributed as the graph-aave-mcp package.
🛠️ Key Features
AAVE V2 and AAVE V3 lending and governance support
Uses The Graph subgraphs
Covers 7 chains
🚀 Use Cases
Query AAVE lending information across multiple chains
Retrieve governance-related data for AAVE v2/v3 deployments
⚡ Developer Benefits
Clear alignment with Graph subgraph data sources
Packaged and published as graph-aave-mcp on npm
MIT-licensed distribution
⚠️ Limitations
Scope is limited to AAVE lending and governance (v2/v3) data via The Graph
Multi-chain coverage is limited to 7 specified chains
# 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
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
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
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)
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
Tool
Description
get_v4_hubs
Liquidity hubs (Core, Plus, Prime) with TVL and utilization
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 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
bash
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
bash
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.
