Graph Uniswap MCP

Simulate a Uniswap swap before you make it — with no RPC, no node, and no key beyond a free Graph API key.

One MCP interface over Uniswap V2, V3 and V4 across Ethereum, Arbitrum, Base, Polygon, Optimism and BSC, powered by The Graph.

quote_swap  pool=0x8ad5…e6d8  tokenIn=WETH  amountIn=100

{ "quotable": true,  "amount_out": 223661.14,  "token_out": "USDC",
  "effective_price": 2236.61,  "spot_price": 2250.80,
  "price_impact_pct": 0.6291,  "fee_pct": 0.3,  "ticks_crossed": 2 }

Why this exists

Most Uniswap tooling can tell an agent what a pool is. Very little can tell it what a trade would actually cost — and that is the only question that precedes moving money.

Uniswap's own routing-api answers it, but it is self-host-only: an AWS CDK deployment plus RPC provider keys. @uniswap/v3-sdk answers it too, but it drags ~300MB of Solidity build artifacts (hardhat → @nomicfoundation/edr-* prebuilt binaries) into node_modules, which is a poor trade for a server launched with npx.

Everything the math needs — sqrtPrice, tick, liquidity, feeTier, and the initialised ticks — is already in the subgraph. So this server fetches that and runs the protocol's own concentrated-liquidity math locally, in ~200 lines of BigInt with zero runtime dependencies beyond the MCP SDK and zod.

We do not ask you to trust that. test/fixtures/v3-quote-oracle.json holds real mainnet pool state plus expected outputs generated by @uniswap/v3-sdk, and npm test asserts every case matches to the wei — including trades that cross 26 initialised ticks. Not "close". Identical. Rounding direction is exactly where a reimplementation of this math goes wrong, so the test tolerates none.

Related MCP server: Uniswap Trader MCP

What it refuses to do

The failure that matters for a pre-trade tool is not an error — it is a confident wrong number, because the caller acts on it and never finds out. So quote_swap returns quotable: false with a reason instead of a figure when it cannot be trusted:

TVL is reported as null, deliberately

Uniswap V3/V4 native subgraphs accumulate totalValueLockedUSD from per-event deltas, and it drifts. Measured 2026-08-19 on the canonical USDC/WETH 0.3% pool:

That is 22.7x high on a blue-chip pool, so "spam-token pools inflate TVL" — the usual explanation, and the one earlier versions of this README gave — does not account for it. Prior versions shipped that number with a caveat string attached. Agents read fields, not prose, so the caveat did nothing.

tvl_usd is now null on V3/V4 paths. V2 reserve0/reserve1 are real token balances and are still returned. For actual depth, use quote_swap — simulating the trade is a truthful answer to "how deep is this pool", and a fabricated scalar is not.

Tools

All tools except list_markets take chain plus an optional version (v2/v3/v4). Chain aliases (eth, arb, matic, bnb, …) are accepted.

Coverage, precisely

Omit version and you get V3 wherever it exists. Earlier versions ranked by query traffic, which picked the most queried market rather than the most useful one: chain:"base" landed on V4, whose top pools by volume are zero-liquidity hook pools reporting billions in fabricated volume. Pinning a version always overrides this.

⚠️ Base V4 is servable when pinned, but is not chosen for you: its top pools by volume are hook pools with zero in-range liquidity. Uniswap V4 on Ethereum is the opposite — real hookless pairs (USDC/USDT, WBTC/cbBTC, ETH/USDC) with a ticks entity, so quote_swap works there too.

Pool field names are detected, not assumed: V3 uses feeTier/sqrtPrice/feesUSD while uniswap-v4-ethereum uses fee/sqrtPriceX96/totalFeesUSD and exposes tickSpacing. A new deployment with either convention works without a code change.

Ranking is always by volumeUSD, never TVL — a single spam-token pool can claim trillions in fake liquidity, so a TVL sort returns junk at the top. This holds even on subgraphs whose per-pool TVL is accurate.

discover_markets only heals what is broken

apply: true used to install the top GRT-signal name match unconditionally, which could displace Uniswap Labs' canonical deployment with a stranger and break the market for the rest of the session — invisibly, since list_markets still showed the old id. It now probes the incumbent first, keeps it if healthy, and probes any replacement before installing it. Candidates are always listed in live_signal_candidates whether or not anything is applied.

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.

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

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

Claude Code:

claude mcp add uniswap -e GRAPH_API_KEY=your_key_here -- npx -y graph-uniswap-mcp

Try it

"What would selling 100 WETH into the USDC/WETH 0.3% pool on Ethereum actually get me?"

"Compare price impact for a 50 ETH sell across the 0.05% and 0.3% pools."

"Find the USDC/WETH pools on Base and show me recent swaps."

Accuracy envelope

Be precise about what the number means:

• The simulation runs against the subgraph's most recently indexed block, not the pending state. Real execution depends on the state at inclusion — MEV, pending swaps and indexer lag all move it.

• It is a single-pool simulation. It does not split across pools or hops; it is not a router.

• Exact-input only.

• V2 uses constant-product math (exact). V3/V4 use tick-walking math, wei-exact versus @uniswap/v3-sdk on the pinned oracle.

Development

npm ci
npm run build
npm test          # offline gate: MCP handshake + tool registry + wei-exact swap math
npm run test:live # deeper checks against live subgraphs (needs GRAPH_API_KEY)

To regenerate the oracle fixture (the only thing that needs the Uniswap SDK installed):

npm i --no-save @uniswap/v3-sdk @uniswap/sdk-core
node scripts/gen-oracle.mjs

License

MIT