graph-aave-mcp

MCP server for querying AAVE V2/V3 lending protocol and governance data via The Graph subgraphs.

Exposes 14 tools and 5 guided prompts that any AI agent (Claude, Cursor, Copilot, etc.) can use to query lending markets, user positions, health factors, liquidations, flash loans, rate history, and AAVE governance — across 7 chains (Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, Fantom) via 11 subgraphs covering both V2 and V3 deployments plus AAVE Governance V3.

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.

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

Lending Markets

User Positions

Protocol Events

Governance

Advanced

Guided Prompts

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

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