graph-aave-mcp

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

Supported Chains & Subgraphs

7 chains, 11 subgraphs — some chains have both V2 (legacy) and V3 deployments tracked separately.

Chain	Version	Deployment ID
Ethereum	V3	QmX2VfvEspbShTdcjefWeG3CKBVXKWm9naxH6TVhqPb9qY
Ethereum	V2	QmdEuhCPTFx5q1Vf7jPQDVGQDpC34KYry82yb3NPc9sK6a
Base	V3	QmXZ53Kzz3L2LvvbGve2ebtLKWMhjjB1a3U2jnUj2YwGCW
Arbitrum	V3	Qmdn5hAZZj3wmWVuksXHtua3E6aWftCDeTFcW8YQ8Lu6pB
Polygon	V3	QmceoHP3ekxJ6JYqAXhqrVgv8rb9WXumrGe1ZhVZah8Ar5
Polygon	V2	QmNfojj4Wu1DErB9iC6epPZc4K2zQCrm4KJUra3DMQqSNm
Optimism	V3	QmScPH3aFxzFgrie8MMDU4QtFu3CE7nTfsRfSQXiccxBPh
Avalanche	V3	QmXhWmYZyEr8PGEic8F739wVqvMYxHLD7jke69RXmwQU95
Avalanche	V2	QmdDSA73QkFAvRZqtRoHgLvxonuSZTuJhoWkmBtEdVuTmz
Ethereum	Governance V3	QmRyQo7xz4P3WvthdVzfkhwSzfwa8Uku1qrcyJCAN6RAWS
Fantom	V3	QmNTzi2eFS2boHFFY372xrxGHNM8yPjF26H3eUxWTtnvoA

Prerequisites

You need a free Graph API key (takes ~2 minutes):

1. Go to The Graph Studio
2. Connect your wallet (MetaMask, WalletConnect, etc.)
3. Click "API Keys" in the sidebar and create one
4. Free tier includes 100,000 queries/month

Installation

npm install -g graph-aave-mcp

Or use directly with npx (no install needed):

GRAPH_API_KEY=your-key npx graph-aave-mcp

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code (CLI)

claude mcp add graph-aave -- npx -y graph-aave-mcp

Then set the environment variable:

export GRAPH_API_KEY=your-api-key-here

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Other MCP Clients

Use stdio transport with npx graph-aave-mcp as the command and GRAPH_API_KEY as an environment variable.

Available Tools

Discovery

Tool	Description
list_aave_chains	List all supported AAVE chains with subgraph IDs, versions, and 30-day query volumes
get_aave_schema	Full GraphQL schema introspection for any chain's subgraph

Lending Markets

Tool	Description
get_aave_reserves	All active lending markets on a chain — TVL, supply APY, borrow APY, LTV, liquidation thresholds
get_aave_reserve	Deep detail on one asset: lifetime stats, full config, token addresses
get_reserve_rate_history	Historical snapshots of APY, utilization rate, and TVL over time

User Positions

Tool	Description
get_aave_user_position	Wallet's supplied assets, borrowed assets, collateral flags, and e-mode category
simulate_health_factor	Simulate how a price change affects a user's health factor — e.g. "ETH drops 20%"

Protocol Events

Tool	Description
get_recent_borrows	Recent borrow events — filterable by user address or asset symbol
get_recent_supplies	Recent supply/deposit events (handles V2 deposit vs V3 supply automatically)
get_aave_liquidations	Recent liquidations — filterable by liquidated user or liquidator address
get_aave_flash_loans	Recent flash loans with amounts and fees paid

Governance

Tool	Description
get_governance_proposals	AAVE Governance V3 proposals with titles, states, for/against vote counts
get_proposal_votes	Individual voter breakdown for a specific proposal by voting power

Advanced

Tool	Description
query_aave_subgraph	Raw GraphQL escape hatch — execute any query against any chain

Guided Prompts

Prompts are pre-built multi-step workflows that guide any AI agent through common AAVE analysis tasks:

Prompt	Description
analyze_aave_user	Full wallet analysis: supplied/borrowed assets, health factor, liquidation risk
aave_chain_overview	Protocol overview for a chain: top markets, rates, recent activity
compare_aave_rates	Compare supply/borrow APY for one asset across all supported chains
aave_liquidation_analysis	Analyze liquidation patterns, top liquidators, and at-risk markets
aave_governance_overview	Recent governance proposals, voting results, and active decisions

Rate Conversion

AAVE stores interest rates in RAY units (27 decimal precision). To convert to human-readable APY:

Supply APY %  = liquidityRate    / 1e27 * 100
Borrow APY %  = variableBorrowRate / 1e27 * 100

Token amounts are stored in native token units. To convert:

Human amount = rawAmount / 10^decimals

Health Factor

A user's health factor determines liquidation risk:

HF = Σ(collateral_i × price_i × liquidationThreshold_i) / Σ(debt_i × price_i)

• HF > 1.0 — position is safe
• HF = 1.0 — liquidation threshold reached
• HF < 1.0 — position is liquidatable

Use simulate_health_factor to test how price movements affect a specific wallet's HF.

Example Prompts for AI Agents

Once connected, an AI agent can answer questions like:

Markets & Rates

• "What are the top AAVE markets on Ethereum by TVL?"
• "What is the current USDC supply APY on Base?"
• "Compare WETH borrow rates across all AAVE V3 chains"
• "Which chain has the cheapest stablecoin borrowing right now?"

User Positions

• "Analyze the AAVE position for wallet 0x..."
• "What is the health factor for address 0x... on Arbitrum?"
• "Show me what 0x... has supplied and borrowed on Polygon"
• "If ETH drops 30%, will address 0x... get liquidated?"

Protocol Activity

• "Show me the last 20 liquidations on Ethereum AAVE"
• "Who are the most active liquidators on Arbitrum this week?"
• "What are the biggest flash loans on Base recently?"
• "Show me recent USDC borrows on Optimism"

Governance

• "What are the latest AAVE governance proposals?"
• "Is there anything currently up for a vote in AAVE governance?"
• "Show me who voted on proposal #185 and how"
• "What governance proposals have passed recently?"

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

To test with a specific chain:

# Start the server and query it with a GraphQL client or MCP inspector
GRAPH_API_KEY=your-key npx @modelcontextprotocol/inspector node build/index.js

Schema Notes

Lending subgraphs (V3) use AAVE-native schema:

• reserves — individual asset markets
• userReserves — user positions per asset
• borrows, supplies, repays — transaction events
• liquidationCalls — liquidation events
• flashLoans — flash loan events
• reserveParamsHistoryItems — historical rate snapshots

Lending subgraphs (V2) use the same schema but with deposits instead of supplies.

Governance subgraph uses a separate schema:

• proposals — governance proposals with votes and payloads
• proposalVotes_collection — individual voter records
• proposalMetadata_collection — proposal titles and content
• payloads — on-chain execution payloads
• votingPortals, votingConfigs — governance configuration

License

MIT