graph-aave-mcp is an MCP server for querying AAVE V2/V3/V4 lending and governance data. Through three data sources—The Graph subgraphs, the Aave V4 API, and the V4 Omnigraph—it provides 51 tools, covering 17 Graph subgraphs, and supports 7 chains in total—Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, and Fantom—as well as Governance V3.
In terms of use cases, this server is aimed at scenarios that require analyzing AAVE protocol data, including lending market status, user positions, health factors, cross-chain liquidation risk monitoring, liquidation records, flash loans, governance proposals, V4 hubs/spokes, exchange rates, swap quotes, rewards, and protocol history.
Its main capabilities fall into several categories. V2/V3 tools are based on The Graph subgraphs and provide 15 tools plus 1 raw query entry point, requiring GRAPH_API_KEY. Among them, get_aave_reserves returns all active reserves by default, which on Ethereum is 67 reserves and about 28k tokens; a single asset can be specified via symbols: ["USDC"] (about 675 tokens), compact: true returns only interest rates, or limit can be used to restrict the number of rows. get_v4_reserves also supports these three options. The liquidation risk tools are a newly added feature, comprising 8 tools, powered by a dedicated risk subgraph, covering 5 chains, requiring GRAPH_API_KEY, and providing real-time liquidation risk monitoring, including health factors, risk scores (0–100), risk level classification (safe/warning/danger/critical), and cross-chain risk summaries. V4 tools are based on api.v4.aave.com/graphql and provide 17 tools with no API key required (api.aave.com/graphql is an alias for the same schema and can be overridden via AAVE_V4_API_URL). V4 Omnigraph tools are based on the aave-v-4 subgraph (QmcKrCRSPrMABEfQjyPF6DqhbY7zzcEj6h5QxQmKLcHFSs) and provide 5 tools, requiring GRAPH_API_KEY, to fill data gaps not exposed by the Aave API, including Hub↔Spoke flow events, per-user risk premium trajectories, post-liquidation analysis with full premium spread context, treasury/fee/deficit accounting, and governance trajectory snapshots.
In terms of usage, users need to obtain a free Graph API key (thegraph.com/studio, free tier 100K queries per month), and may also optionally use a hosted deployment (no installation required). The project provides 7 prebuilt workflows that guide agents through multi-step analysis. Example questions include: which Aave positions on Arbitrum are closest to liquidation, a cross-chain risk dashboard, whether a wallet is at liquidation risk on any chain, recent risk alerts, how a wallet's health factor on Base changes over time, Aave V4 hubs and their utilization, the asset with the highest supply APY among V4 reserves, the current price of ETH on Aave V4, a comparison of V3 and V4 USDC supply rates, Aave V4 spokes on Ethereum, the top AAVE markets on Ethereum ranked by TVL, a comparison of WETH borrow rates across all V3 chains, analyzing a wallet's AAVE position, whether an address would be liquidated if ETH drops 30%, the most recent 20 liquidations on Ethereum, currently active AAVE governance proposals, and more.
In terms of testing, test/smoke.mjs starts the server via stdio and calls every registered tool, failing if any tool returns an error or an unexpected empty collection. Tools whose backend is unavailable in the current environment (no Graph key, no reachable RPC) are skipped rather than failed, so the test suite remains meaningful without credentials and becomes more comprehensive with them. This test exists because get_v4_hub_flows once pointed to an undeployed subgraph without being detected: Graph Studio returns HTTP 200 and {"message":"Not found"} for a missing subgraph, the client only checks the GraphQL errors key, and the tool returns flows: [], which is indistinguishable from "no on-chain activity." Now every backend call fails explicitly.
In terms of limitations, V2/V3 tools, liquidation risk tools, and V4 Omnigraph tools require GRAPH_API_KEY; V4 API tools do not require a key. Some tools depend on specificAvailability of subgraphs or RPCs. The project has been published to the MCP Registry under the identifier io.github.PaulieB14/graph-aave-mcp. Further details such as environment variables are not yet available.
