Graph Polymarket MCP

graph-polymarket-mcp

MCP server for querying [Polymarket](https://polymarket.com/) prediction market data via [The Graph](https://thegraph.com/) subgraphs and Polymarket REST APIs.

Exposes 31 tools that AI agents (Claude, Cursor, etc.) can use to search markets, get real-time CLOB prices and order books, query on-chain data, trader P&L, positions, activity, open interest, market resolution status, and trader profiles.

v2.0.0 — adds 10 new tools powered by Polymarket's Gamma and CLOB APIs (inspired by polymarket-cli): market search, event browsing, live prices, spreads, order books, price history, and more. No API key needed for these tools — they hit Polymarket's public REST endpoints directly.

Published to the MCP Registry as io.github.PaulieB14/graph-polymarket-mcp

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-polymarket-mcp

Or use directly with npx:

npx graph-polymarket-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "graph-polymarket": { "command": "npx", "args": ["-y", "graph-polymarket-mcp"], "env": { "GRAPH_API_KEY": "your-api-key-here" } } } }

Claude Code

claude mcp add graph-polymarket -- npx -y graph-polymarket-mcp

Set the environment variable GRAPH_API_KEY before running.

Cursor / Other MCP Clients

Use the stdio transport with npx graph-polymarket-mcp as the command, passing GRAPH_API_KEY as an environment variable.

OpenClaw / Remote Agents (SSE)

The SSE transport has no authentication. Anyone who can reach the port can call every tool,

and those calls spend *your* GRAPH_API_KEY quota. --http binds 0.0.0.0 inside a container,

so publish it to 127.0.0.1 on the host and put a reverse proxy with TLS and auth in front of

anything reachable off-box. For local agents, prefer the default stdio transport — it has no

network surface at all.

Start the server with the HTTP transport:

# Dual transport — stdio + SSE on port 3851

GRAPH_API_KEY=your-key npx graph-polymarket-mcp --http

SSE only (for remote/server deployments)

GRAPH_API_KEY=your-key npx graph-polymarket-mcp --http-only

Custom port

MCP_HTTP_PORT=4000 GRAPH_API_KEY=your-key npx graph-polymarket-mcp --http

Then point your agent at the SSE endpoint:

{

"mcpServers": { "graph-polymarket": { "url": "http://localhost:3851/sse" } } }

Transport Modes

A /health endpoint is available at http://localhost:3851/health when HTTP transport is active.

Available Tools

Core Tools

Domain-Specific Tools

Polymarket REST API Tools (no Graph API key needed)

CLOB V2 Tools

Polymarket migrated to V2 exchange contracts on 2026-04-28. These tools read the V2 subgraphs, which index from block 84902353 and hold no pre-migration history — V1 and V2 are different eras, not old and new.

Builder attribution is the capability V2 adds. Every V2 fill carries the builder code of the frontend, bot or integrator that routed it, so "who is actually routing this flow" becomes an answerable question — 3,325 builders as of 2026-08-08.

Two traps these tools handle for you. The V2 exchange contracts appear as Account rows, because the exchange is the taker when an order matches the book — ranking accounts naively returns 0xe111…996b (176M fills) and 0xe222…0f59 (41M fills) above every human. get_v2_top_traders excludes them. check_subgraph_freshness reports any subgraph's head block before you trust a number.

Data Sources

The Graph Subgraphs (requires GRAPH_API_KEY)

On-chain indexed data — authoritative for historical analytics, P&L, open interest, and resolution status.

Subgraphs

CLOB V2 — primary (from block 84902353)

Status verified via _meta on 2026-10-15.

V1 — legacy (pre-2026-04-28 migration history)

Open Interest is already a V2 deployment; it reads ConditionalTokens, which V2 left unchanged, so it has no migration discontinuity.

Which era to ask: all-time or pre-2026-04-28 → V1. Post-migration activity, or anything about builders → V2. beefy_pnl keeps the hedge-fund metrics (winRate, profitFactor, maxDrawdown, daily series) that V2 P&L does not have, so trader-quality scoring stays on V1.

Example Queries

Once connected, an AI agent can:

Market Discovery (Gamma API)

• "Search for prediction markets about AI"
• "Show me the most active Polymarket events right now"
• "Find markets about the 2024 election sorted by volume"
• "What markets are in the 'crypto' category?"

Live Trading