# graph-aave-mcp

<div align="center">

[![npm version](https://img.shields.io/npm/v/graph-aave-mcp)](https://www.npmjs.com/package/graph-aave-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.PaulieB14/graph-aave-mcp)
[![smithery badge](https://smithery.ai/badge/paulieb14/graph-aave-mcp)](https://smithery.ai/servers/paulieb14/graph-aave-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<a href="https://glama.ai/mcp/servers/@PaulieB14/graph-aave-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@PaulieB14/graph-aave-mcp/badge" />
</a>

**MCP server for [AAVE](https://aave.com/) V2, V3, and V4 — 57 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](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.PaulieB14/graph-aave-mcp) 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

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

<details>
<summary>Claude Desktop / Cursor config</summary>

```json
{
  "mcpServers": {
    "graph-aave": {
      "command": "npx",
      "args": ["-y", "graph-aave-mcp"],
      "env": {
        "GRAPH_API_KEY": "your-api-key-here"
      }
    }
  }
}
```
</details>

Free Graph API key: [thegraph.com/studio](https://thegraph.com/studio/) (100K queries/month free tier).

**Hosted deployment** (no install): [Fronteir AI](https://fronteir.ai/mcp/paulieb14-graph-aave-mcp)

---

## 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`](https://thegraph.com/explorer)). **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 Subgraph Tools — Base (Coinbase tokenized stocks) + Ethereum

6 network-aware tools backed by the Aave V4 subgraph. **Default `network: "base"`** — the Coinbase Stocks hub on Base ([subgraph `9x1tg7KX3RXspnK7R1mahAZsM5gTmFhLrmJSbkoBsDdq`](https://thegraph.com/explorer/subgraphs/9x1tg7KX3RXspnK7R1mahAZsM5gTmFhLrmJSbkoBsDdq)). Pass `network: "ethereum"` for Core/Plus/Prime. **Requires `GRAPH_API_KEY`.**

| Tool | Description |
|------|-------------|
| `get_v4_recent_liquidations` | Liquidations newest-first, filter by `liquidator` / `user` / `sinceHours`; collateral seized, debt restored, shares, premium deltas, per-liquidator counts |
| `get_v4_hub_assets` | Per-asset borrow rate %, liquidity fee %, accrued protocol fees, fee receiver, IR strategy |
| `get_v4_config_changes` | Hub↔spoke cap snapshots, reserve config snapshots, liquidation-config snapshots, position-manager whitelist (optional `spoke`) |
| `get_v4_hub_daily_flows` | Daily supplied/withdrawn/borrowed/repaid/deficit per hub asset, optional raw flow events |
| `get_v4_user_activity` | User risk premium + history, liquidations suffered, supply/withdraw/borrow/repay/collateral activity |
| `get_v4_treasury_events` | Merged FeeMint / Sweep / Reclaim / DeficitEliminated / ReportDeficit stream |

Example: *"Who's liquidating tokenized stocks on Aave V4 Base?"* → `get_v4_recent_liquidations`. *"What's the USDC borrow rate and fees on the Base stocks hub?"* → `get_v4_hub_assets` (≈2.1%, 10% liquidity fee).

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

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

## Environment variables

| Variable | Needed for | Notes |
|---|---|---|
| `GRAPH_API_KEY` | all subgraph + Omnigraph tools | [Free key](https://thegraph.com/studio/apikeys/). 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_BASE_SUBGRAPH_ID` | V4 subgraph tools (`network: base`) | Defaults to `9x1tg7KX3RXspnK7R1mahAZsM5gTmFhLrmJSbkoBsDdq`. |
| `AAVE_V4_OMNIGRAPH_URL` | Omnigraph tools | Set only to bypass the gateway for a self-hosted/Studio deployment. |

## License

MIT