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 top traders by PnL"
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.
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
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: Polymarket MCP Server
npm install -g graph-polymarket-mcpOr use directly with npx:
npx graph-polymarket-mcpAdd 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 mcp add graph-polymarket -- npx -y graph-polymarket-mcpSet the environment variable GRAPH_API_KEY before running.
Use the stdio transport with npx graph-polymarket-mcp as the command, passing GRAPH_API_KEY as an environment variable.
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"
}
}
}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.
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 |
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 |
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 |
GRAPH_API_KEY)On-chain indexed data — authoritative for historical analytics, P&L, open interest, and resolution status.
Name | IPFS Hash | Description |
Main |
| Complete ecosystem data |
Beefy P&L |
| Comprehensive P&L tracking |
Slimmed P&L |
| Minimal position data |
Activity |
| Position management events |
Orderbook |
| Order fill analytics |
Open Interest |
| Per-market and global OI with hourly snapshots |
Resolution |
| UMA oracle resolution lifecycle |
Traders |
| Per-trader event logs and USDC flows |
Once connected, an AI agent can:
"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?"
"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"
"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)
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.jsMIT
Get a trader's P&L and performance metrics from the Beefy P&L subgraph
Inputs: account (required).
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 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 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 the total open interest across all Polymarket markets — the aggregate USDC locked in outstanding positions platform-wide.
Inputs: no named parameters.
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 the last trade price for a Polymarket outcome token from the CLOB.
Inputs: tokenId (required).
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 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 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 Polymarket market/condition data including outcomes and volumes from the Main subgraph
Inputs: first, orderBy, orderDirection.
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 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 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 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 moderator revisions/updates for Polymarket markets. Shows when and how moderators intervened in market resolution.
Inputs: first, questionId.
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 recent order fills from the Orderbook subgraph
Inputs: first, maker, taker.
Get a single Polymarket event with all its associated markets. An event groups related prediction markets under one topic.
Inputs: eventId (required).
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 splits, merges, and redemptions from the Activity subgraph
Inputs: first, account.
Get the full GraphQL schema (introspection) for a Polymarket subgraph
Inputs: subgraph (required).
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 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 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 a user's current positions from the Slimmed P&L subgraph. Falls back gracefully if indexers are behind.
Inputs: account (required).
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 all available Polymarket subgraphs with descriptions and key entities
Inputs: no named parameters.
Execute a custom GraphQL query against a Polymarket subgraph
Inputs: query (required), subgraph (required), variables.
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.
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.
Search Polymarket events (sports matches, elections, etc.) and get their sub-markets + live prices using keyword search. Best for finding sports match markets like 'Spain France'.
Inputs: query (required), limit, active.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 32 tools
Several tools have overlapping purposes (e.g., get_market_data vs get_market_info, search_markets vs search_markets_enriched, and the multiple live CLOB tools). Descriptions help differentiate them, but misselection is still possible.
Most tools follow a get_ prefix with snake_case (e.g., get_market_resolution, get_live_orderbook), but a few use search_, list_, or query_, and search_markets_enriched adds an inconsistent suffix. The pattern is mostly consistent but has deviations.
32 tools is excessive for a single server. Many tools are excessively granular (e.g., get_live_prices, get_live_spread, get_live_orderbook, get_last_trade could be one tool with parameters), making the surface feel bloated.
The server covers the main needs of Polymarket data consumers: market discovery, live order book, trader analytics, resolution status, and platform stats. Minor gaps exist (e.g., per-trader trade history), but the core is solid.
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.
Read-only Polymarket search, market details, order books, price history, and market cards.
