Graph Uniswap

npm version npm downloads license node

One MCP interface over Uniswap V2, V3, and V4 across Ethereum, Arbitrum, Base, Polygon, Optimism, and BSC — powered by The Graph. Ask an agent for a price, the top pools, a pair, or recent swaps on any Uniswap deployment and get back clean JSON.

Built to be correct where naive subgraph access goes wrong:

• 🔁 Self-healing — markets are addressed by subgraph ID, so queries always follow the publisher's latest published version. discover_markets re-resolves the best live subgraph from The Graph's network subgraph (ranked by curation signal), so new or replacement deployments surface with no code change.
• 🧬 Schema-adaptive — Uniswap's subgraphs are not uniform (V2 pairs vs V3/V4 pools; classic ethPriceUSD/derivedETH vs newer nativePriceUSD/derivedNative). The server introspects each subgraph once and adapts every query automatically.
• 🚫 Footgun-proofed — Uniswap subgraph TVL is unreliable (one spam-token pool can report trillions in fake liquidity). Every ranking is by volumeUSD, never TVL, and TVL is always returned with a caveat. Prices are derived on-chain and easy to sanity-check (a stablecoin reads ~$1).

Tools

Every tool takes chain and an optional version (v2/v3/v4). Omit version and it uses the highest-volume version on that chain. Chain aliases (eth, arb, matic, bnb, …) are accepted.

Setup

1. Get a free Graph API key at https://thegraph.com/studio (Billing → API Keys — first 100k queries/month are free).

2. Add the server to your MCP client. No install needed — npx fetches the published build.

{
  "mcpServers": {
    "graph-uniswap": {
      "command": "npx",
      "args": ["-y", "graph-uniswap-mcp"],
      "env": { "GRAPH_API_KEY": "your_key_here" }
    }
  }
}

claude mcp add-json graph-uniswap '{"command":"npx","args":["-y","graph-uniswap-mcp"],"env":{"GRAPH_API_KEY":"your_key_here"}}'

Prefer keyless, pay-per-query access (no API key, gasless USDC on Base)? See PayQL — discover + pay-per-query The Graph over x402.

git clone https://github.com/PaulieB14/graph-uniswap-mcp && cd graph-uniswap-mcp
npm install && npm run build
GRAPH_API_KEY=... npm start   # run the server
npm test                      # offline smoke — no key needed
npm run test:live             # full stress suite (needs GRAPH_API_KEY + network)

Example calls

get_token_price  { "token": "WETH", "chain": "arbitrum" }
top_pools        { "chain": "base", "version": "v4", "first": 5 }
find_pool        { "tokenA": "WBTC", "tokenB": "USDC", "chain": "ethereum" }
recent_swaps     { "chain": "base", "version": "v4", "first": 10 }
discover_markets { "chain": "arbitrum", "version": "v3" }

Covered markets

13 markets, each backed by a canonical Uniswap-Labs subgraph addressed by subgraph ID (so it auto-follows the publisher's latest version). Query volumes are a rough popularity signal from the operator dashboard.

Call list_markets for this table live, or discover_markets to re-resolve the best current subgraph from The Graph's network subgraph. (V4 is not yet deployed on Polygon.)

Reliability

Built for agents that can't babysit a hung tool call:

• Fail-fast, never hang. Every gateway request is time-boxed by an AbortController (default 15s/attempt), so a stalled indexer returns a clean error instead of hanging your agent. Only genuinely transient failures (indexer lag, 5xx) retry.
• Version fallback (self-healing on the data path). When you don't pin a version and the top market's indexers are down, the server transparently falls back to the next-highest-volume version on that chain and still returns real data — the response's served field tells you which version answered. A pinned version is never silently swapped.
• Tunable via env: GRAPH_HTTP_TIMEOUT_MS (15000), GRAPH_MAX_ATTEMPTS (2), GRAPH_TOTAL_BUDGET_MS (25000).

Keyless pay-per-query (x402)

This server uses a shared GRAPH_API_KEY (free tier: 100k queries/month). If you'd rather an agent pay per query with no API key or account at all, pair it with PayQL — an MCP that runs any Graph subgraph query (including all the Uniswap subgraphs above) over x402, paying ~$0.01 in USDC per call via the gateway's …/api/x402/… path. Gasless (EIP-3009), keyless, wallet-agnostic — the payment is the auth. Use this MCP for the curated Uniswap tools, and PayQL when you want the raw, key-free pay-as-you-go path.

License

MIT © PaulieB14