A
licenseB
qualityD
maintenanceEnables interaction with the PolyMarket API to fetch prediction market data such as market information, prices, and historical data, with robust error handling and rate limit management.
4
144
MIT
graph-polymarket-mcp
by PaulieB14
Summary: Query Polymarket prediction market data via The Graph subgraphs and Polymarket REST APIs (Gamma/CLOB), exposing 31 tools for market discovery, live pricing, on-chain analytics, trader P&L, and V2 builder attribution.
Browse subgraphs & run raw GraphQL — list subgraphs, fetch full schemas, execute custom queries (V1 legacy + V2).
Discover markets & events (no API key) — text search with active/closed/volume/liquidity filters, fetch market metadata by slug or condition ID, list and inspect events by tag/status.
Get live trading data (no API key) — real-time CLOB prices (single/batch), bid-ask spreads, full order books, price history, last trade, and CLOB market details (token IDs, tick sizes).
Search + auto-enrich in one call — search markets enriched with live CLOB prices and on-chain resolution status.
Market analytics (Graph) — market/condition data with outcomes, platform global stats, open interest leaders, hourly OI history, platform-wide OI total.
Resolution & oracle tracking — UMA resolution status, disputed markets, moderator revisions.
Trader & account analytics — trader P&L and metrics (win rate, profit factor, max drawdown), top-trader leaderboards, top holders per outcome token, user positions with orderbook cross-checks, unified splits/merges/redemptions/fills activity feed, USDC deposit/withdrawal flows, full trader profiles.
Orderbook trades — recent fills with maker/taker filtering.
V2 / builder analytics — builder leaderboard and per-builder activity (builder-code attribution, a V2-only capability), V2 top traders with exchange contracts excluded, and subgraph freshness checks against chainhead.
Enables querying of Polymarket prediction market data via The Graph subgraphs using GraphQL, providing tools to execute custom queries and retrieve detailed schemas for markets, traders, and activity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@graph-polymarket-mcp Show me the P&L for trader 0x71C444E949e1A9159d282E376E6c986C887565B1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
graph-polymarket-mcp
MCP server for querying Polymarket prediction market data via The Graph 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):
Go to The Graph Studio
Connect your wallet (MetaMask, WalletConnect, etc.)
Click "API Keys" in the sidebar and create one
Free tier includes 100,000 queries/month
Related MCP server: TheGraph MCP Server
Installation
npm install -g graph-polymarket-mcpOr use directly with npx:
npx graph-polymarket-mcpConfiguration
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-mcpSet 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_KEYquota.--httpbinds0.0.0.0inside a container, so publish it to127.0.0.1on 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 --httpThen point your agent at the SSE endpoint:
{
"mcpServers": {
"graph-polymarket": {
"url": "http://localhost:3851/sse"
}
}
}Transport Modes
Invocation | Transports | Use case |
| stdio | Claude Desktop, Cursor, Claude Code |
| stdio + SSE :3851 | Dual — local + remote agents |
| SSE :3851 | OpenClaw, remote deployments |
A /health endpoint is available at http://localhost:3851/health when HTTP transport is active.
Available Tools
Core Tools
Tool | Description |
| List all available Polymarket subgraphs with descriptions and key entities |
| Get the full GraphQL schema for a specific subgraph |
| Execute a custom GraphQL query against any subgraph |
Domain-Specific Tools
Tool | Description | Subgraphs |
| Get market/condition data with outcomes and resolution status | Main |
| Get platform stats: market counts + real volume/fees/trades | Main + Orderbook |
| Get a trader's P&L and performance metrics (winRate, profitFactor, maxDrawdown) | Beefy P&L |
| Leaderboard ranked by PnL, winRate, volume, or profitFactor. Cross-refs Orderbook to flag rows where OB volume exceeds Beefy-tracked volume and surface OB-only traders absent from the leaderboard. | Beefy P&L + Orderbook |
| Daily volume, fees, trader counts, and market activity (1–90 days) | Beefy P&L |
| Top holders for a specific outcome token with their P&L | Beefy P&L |
| Current token positions. Cross-refs Orderbook: flags ⚠ orderbook-only entry when | Slimmed P&L + Orderbook |
| Unified chronological feed interleaving splits, merges, and redemptions with orderbook fills. Supports optional address filter. | Activity + Orderbook |
| Get recent order fills with maker/taker filtering | Orderbook |
| Top markets ranked by USDC locked in outstanding positions. Cross-refs Main subgraph to flag ⚠ dead money OI on resolved markets (losing-side tokens that will never be redeemed on-chain). | Open Interest + Main |
| Hourly OI snapshots for a specific market (for charting trends) | Open Interest |
| Total platform-wide open interest and market count | Open Interest |
| UMA oracle resolution status with filtering by status | Resolution |
| Markets disputed during oracle resolution (high-signal events) | Resolution |
| Moderator interventions and updates on market resolution | Resolution |
| Full trader profile combining CTF events and USDC flows with Orderbook fills. Classifies wallet as hybrid / orderbook-only / split-collateral-only and warns when P&L subgraphs are unreliable. | Traders + Orderbook |
| USDC deposit/withdrawal history with direction filtering | Traders |
Polymarket REST API Tools (no Graph API key needed)
Tool | Description | API |
| Search markets by text query with filters (active, closed, sort by volume/liquidity) | Gamma |
| Get detailed market metadata by slug or condition ID | Gamma |
| Browse events (groups of related markets) with tag/status filters | Gamma |
| Get a single event with all its associated markets | Gamma |
| Real-time CLOB prices for outcome tokens (buy/sell, single or batch) | CLOB |
| Bid-ask spread + midpoint for assessing market liquidity | CLOB |
| Full order book (all resting bids and asks) for a token | CLOB |
| Historical price time-series (1m to max interval, configurable fidelity) | CLOB |
| Last trade price for an outcome token | CLOB |
| CLOB market details: token IDs, live prices, min order/tick sizes | CLOB |
| Power tool: search + auto-enrich with live CLOB prices AND on-chain resolution status in one call | Gamma + CLOB + Graph |
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.
Tool | Description | Subgraphs |
| Rank V2 builders by routed volume, order count or fees, with each builder's share of V2 volume. No V1 equivalent — the V1 contracts never emitted a builder code | V2 Orderbook |
| Recent fills routed by one builder code, plus that builder's aggregate totals | V2 Orderbook |
| Top real V2 traders, with the exchange contracts filtered out | V2 Orderbook |
| How far behind chainhead any subgraph is, read live from its | Any |
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)
Name | IPFS Hash | Status | Description |
V2 Main |
| at chainhead | Conditions, resolution status and counters (default for market tools) |
V2 Orderbook |
| at chainhead | V2 fills with builder-code attribution |
V2 P&L |
| at chainhead | Cost basis and realized P&L from V2 fills only |
Open Interest V2 |
| ⚠️ no indexer allocated (2026-10-15) | Per-market and global OI with hourly snapshots |
Status verified via _meta on 2026-10-15.
V1 — legacy (pre-2026-04-28 migration history)
Name | IPFS Hash | Description |
Main (legacy) |
| All-time conditions incl. pre-migration; pass |
Beefy P&L |
| Comprehensive P&L tracking |
Slimmed P&L |
| Minimal position data |
Activity |
| Position management events |
Orderbook |
| Order fill analytics (all-time volume) |
Resolution |
| UMA oracle resolution lifecycle |
Traders |
| Per-trader event logs and USDC flows |
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 Data (CLOB API)
"What's the current price for the Trump YES token?"
"Show me the full order book for this market"
"What's the bid-ask spread on this token?"
"Show me the price history for this market over the last week"
On-Chain Analytics (The Graph)
"What are the current Polymarket global stats?"
"Show me the latest 20 orderbook trades"
"What are the positions for address 0x...?" (flags if wallet entered via OB buys only)
"Get the P&L for trader 0x...?"
"Which markets have the most open interest right now?" (flags dead-money OI on resolved markets)
"Show me disputed markets on Polymarket"
"Who are the top traders?" (flags any with OB volume not captured by Beefy P&L)
"Show me the full trading history for wallet 0x..." (includes OB fills + entry type classification)
Development
git clone https://github.com/PaulieB14/graph-polymarket-mcp.git
cd graph-polymarket-mcp
npm install
npm run build
GRAPH_API_KEY=your-key node build/index.jsLicense
MIT
Available Tools
35 toolscheck_subgraph_freshnessA
Report how far behind chainhead a subgraph is, by reading its _meta block. Worth calling before trusting any 'current' or 'latest' number, because a lagging subgraph returns stale data rather than an error — it succeeds, it is just answering about the past.
Inputs: subgraph (required).
get_account_pnlA
Get a trader's P&L and performance metrics from the Beefy P&L subgraph
Inputs: account (required).
get_builder_activityA
Recent fills routed by one Polymarket CLOB V2 builder code, with that builder's aggregate totals. Use get_builder_leaderboard first to find a builder id. V2-era only.
Inputs: builderId (required), limit.
get_builder_leaderboardA
Rank Polymarket CLOB V2 builders by routed volume, order count or fees. A 'builder' is the frontend/bot/integrator whose code is attached to a fill — this answers 'who is actually routing the flow', which no V1 subgraph can, because the V1 contracts never emitted it. V2-era only (from block 84902353, migration 2026-04-28).
Inputs: limit, orderBy.
get_clob_marketA
Get CLOB market details by condition ID. Returns token IDs (token_id) with live prices, minimum order/tick sizes, and market status. This is the bridge between on-chain condition IDs and CLOB trading data. Use the returned token_id values with get_live_prices, get_live_spread, get_live_orderbook, get_price_history, or get_market_positions.
Inputs: conditionId (required).
get_daily_statsA
Get daily platform statistics from the Beefy P&L subgraph: volume, fees, trader counts, and market activity per day. Use this for trend analysis and historical performance.
Inputs: days.
get_disputed_marketsB
Get Polymarket markets that were disputed during the UMA oracle resolution process. Disputes happen when someone challenges a proposed outcome — these are high-signal events.
Inputs: first.
get_global_open_interestA
Get the total open interest across all Polymarket markets — the aggregate USDC locked in outstanding positions platform-wide.
Inputs: no named parameters.
get_global_statsA
Get aggregate Polymarket platform statistics. Combines market counts from the Main subgraph with accurate volume/fee/trade data from the Orderbook subgraph.
Inputs: no named parameters.
get_last_tradeA
Get the last trade price for a Polymarket outcome token from the CLOB.
Inputs: tokenId (required).
get_live_orderbookA
Get the full real-time order book (bids and asks) for a Polymarket outcome token from the CLOB. Shows all resting limit orders with prices and sizes.
Inputs: tokenId (required).
get_live_pricesA
Get real-time CLOB prices for Polymarket outcome tokens. Returns the current best price for buying or selling. Token IDs come from: clobTokenIds in search_markets/get_market_info, or token_id in get_clob_market.
Inputs: tokenIds (required), side.
get_live_spreadA
Get the real-time bid-ask spread for a Polymarket outcome token. Returns best bid, best ask, and spread. Useful for assessing market liquidity and trading costs.
Inputs: tokenId (required).
get_market_dataB
Get Polymarket market/condition data including outcomes and volumes from the Main subgraph
Inputs: first, orderBy, orderDirection.
get_market_infoA
Get detailed Polymarket market info by slug or condition ID. Returns full market metadata from the Gamma API including description, prices, outcomes, and CLOB token IDs. Use the returned conditionId to query get_clob_market for live CLOB data, get_market_open_interest for OI, or get_market_resolution for oracle status.
Inputs: slug, conditionId.
get_market_open_interestC
Get the top Polymarket markets ranked by open interest (USDC locked in outstanding positions). This data is unique to the Open Interest subgraph — no other Polymarket subgraph tracks OI.
Inputs: first, orderBy, orderDirection.
get_market_positionsB
Get the top positions for a specific market token from the Beefy P&L subgraph. Shows who holds the largest positions and their P&L.
Inputs: tokenId (required), first, orderBy.
get_market_resolutionA
Get the UMA oracle resolution status for Polymarket markets. Shows whether a market is initialized, proposed, disputed, or resolved, plus proposed/final prices and dispute history.
Inputs: first, status, orderBy, orderDirection.
get_market_revisionsA
Get moderator revisions/updates for Polymarket markets. Shows when and how moderators intervened in market resolution.
Inputs: first, questionId.
get_oi_historyA
Get hourly open interest snapshots for a specific Polymarket market. Use this to chart OI trends over time. The conditionId can be obtained from get_market_open_interest or the main subgraph.
Inputs: conditionId (required), first, orderDirection.
get_orderbook_tradesB
Get recent order fills from the Orderbook subgraph
Inputs: first, maker, taker.
get_polymarket_eventA
Get a single Polymarket event with all its associated markets. An event groups related prediction markets under one topic.
Inputs: eventId (required).
get_price_historyA
Get historical price data for a Polymarket outcome token. Returns time-series price points for charting and trend analysis.
Inputs: tokenId (required), fidelity, interval.
get_recent_activityB
Get recent splits, merges, and redemptions from the Activity subgraph
Inputs: first, account.
get_subgraph_schemaA
Get the full GraphQL schema (introspection) for a Polymarket subgraph
Inputs: subgraph (required).
get_top_tradersA
Get the top Polymarket traders ranked by realized P&L, win rate, or volume from the Beefy P&L subgraph.
Inputs: first, orderBy, minTrades.
get_trader_profileA
Get a trader's on-chain profile from the Traders subgraph: when they first appeared, their recent CTF events (splits, merges, transfers), and USDC flows.
Inputs: address (required), eventLimit.
get_trader_usdc_flowsA
Get USDC deposit/withdrawal history for a trader. Shows inbound and outbound USDC transfers, useful for tracking when traders fund or withdraw from Polymarket.
Inputs: address (required), first, direction.
get_user_positionsA
Get a user's current positions from the Slimmed P&L subgraph. Falls back gracefully if indexers are behind.
Inputs: account (required).
get_v2_top_tradersA
Top real traders on Polymarket CLOB V2 by volume or trade count, with the exchange contracts excluded. Use this rather than querying accounts directly: the V2 exchange is itself the taker when an order matches the book, so it accumulates an Account row and outranks every human by an order of magnitude. V2-era only (from block 84902353).
Inputs: limit, orderBy.
list_polymarket_eventsB
List Polymarket events (groups of related markets). Events bundle multiple Yes/No markets under one topic (e.g. 'US Presidential Election 2024' contains many candidate markets). Uses the Gamma API.
Inputs: tag, limit, active, closed, +2 more.
list_subgraphsA
List all available Polymarket subgraphs with descriptions and key entities
Inputs: no named parameters.
query_subgraphB
Execute a custom GraphQL query against a Polymarket subgraph
Inputs: query (required), subgraph (required), variables.
search_marketsA
Search Polymarket prediction markets by text query. Returns market metadata including question, prices, volume, liquidity, and CLOB token IDs. Uses the Gamma API for real-time market discovery. Chain with: get_clob_market(conditionId) for live order books, get_live_prices(clobTokenIds) for token-level pricing, get_market_open_interest for capital locked, or get_market_resolution for oracle status.
Inputs: query (required), limit, active, closed, +2 more.
search_markets_enrichedA
Power tool: search Polymarket markets then auto-enrich each result with live CLOB prices and on-chain resolution status. Combines Gamma API + CLOB API + The Graph in one call — no need to chain tools manually.
Inputs: query (required), limit, active, closed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3.4/5.0
Scored across 35 tools
Disambiguation2/5
Several tools have overlapping purposes, such as get_market_data, get_market_info, and search_markets, or get_live_prices, get_live_spread, get_last_trade, and get_clob_market. While descriptions do provide some differentiation, the boundaries remain unclear, especially between search_markets and search_markets_enriched, or get_global_stats and get_global_open_interest.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern with snake_case (e.g., get_market_info, search_markets, check_subgraph_freshness). There are no deviations in style, making the naming predictable and coherent.
Tool Count2/5
With 35 tools, the server is overstuffed. While the scope (multiple subgraphs, CLOB, Gamma API) might justify a larger surface, it exceeds the typical 3-15 range and feels heavy. Many tools could be consolidated or removed without loss.
Completeness4/5
The tool set is extremely comprehensive, covering market data, CLOB order books, user positions, P&L, open interest, resolution status, and even custom subgraph queries. Minor gaps exist, such as no direct way to fetch a specific market's full trade history, but overall the domain is well covered.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
Polymarket MCP — prediction-market data via Gamma + CLOB + Data public APIs.
Hosted MCP server for SEC, FRED, Polymarket, Deribit, OKX, and FMP.
Related MCP Servers
- AlicenseAqualityDmaintenancePowers AI agents with indexed blockchain data from The Graph, enabling them to fetch subgraph schemas and execute GraphQL queries against blockchain data.29MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables interaction with Polymarket prediction markets through Claude Desktop.31MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for Polymarket prediction markets, providing real-time market data, prices, and AI-powered analysis tools for Claude Desktop integration.48MIT