graph-aave-mcp

npm version MCP Registry License: MIT

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

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

# 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

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)

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
`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

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

Variable	Needed for	Notes
`GRAPH_API_KEY`	all subgraph + Omnigraph tools	Free key. V4 AaveKit tools work without it.
`ETHEREUM_RPC_URL` (and `BASE_`, `ARBITRUM_`, `POLYGON_`, `OPTIMISM_`, `AVALANCHE_`)	the two live on-chain tools	Optional but recommended — the unconfigured public fallback is rate-limited or blocked on many networks.
`AAVE_V4_API_URL`	V4 AaveKit tools	Defaults to `https://api.v4.aave.com/graphql`.
`AAVE_V4_OMNIGRAPH_DEPLOYMENT_ID`	Omnigraph tools	Defaults to the decentralized-network deployment.
`AAVE_V4_OMNIGRAPH_URL`	Omnigraph tools	Set only to bypass the gateway for a self-hosted/Studio deployment.

License

MIT