graph-polymarket-mcp

![npm version](https://www.npmjs.com/package/graph-polymarket-mcp) ![MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.PaulieB14/graph-polymarket-mcp) ![smithery badge](https://smithery.ai/servers/paulieb14/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.

</div>

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

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)

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

| Invocation | Transports | Use case | |---|---|---| | npx graph-polymarket-mcp | stdio | Claude Desktop, Cursor, Claude Code | | npx graph-polymarket-mcp --http | stdio + SSE :3851 | Dual — local + remote agents | | npx graph-polymarket-mcp --http-only | 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_subgraphs | List all available Polymarket subgraphs with descriptions and key entities | | get_subgraph_schema | Get the full GraphQL schema for a specific subgraph | | query_subgraph | Execute a custom GraphQL query against any subgraph |

Domain-Specific Tools

| Tool | Description | Subgraphs | |------|-------------|-----------| | get_market_data | Get market/condition data with outcomes and resolution status | Main | | get_global_stats | Get platform stats: market counts + real volume/fees/trades | Main + Orderbook | | get_account_pnl | Get a trader's P&L and performance metrics (winRate, profitFactor, maxDrawdown) | Beefy P&L | | get_top_traders | 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 | | get_daily_stats | Daily volume, fees, trader counts, and market activity (1–90 days) | Beefy P&L | | get_market_positions | Top holders for a specific outcome token with their P&L | Beefy P&L | | get_user_positions | Current token positions. Cross-refs Orderbook: flags ⚠ orderbook-only entry when totalBought=0 but OB volume exists, and ⚠ mixed entry when OB volume > 2× split collateral. | Slimmed P&L + Orderbook | | get_recent_activity | Unified chronological feed interleaving splits, merges, and redemptions with orderbook fills. Supports optional address filter. | Activity + Orderbook | | get_orderbook_trades | Get recent order fills with maker/taker filtering | Orderbook | | get_market_open_interest | 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 | | get_oi_history | Hourly OI snapshots for a specific market (for charting trends) | Open Interest | | get_global_open_interest | Total platform-wide open interest and market count | Open Interest | | get_market_resolution | UMA oracle resolution status with filtering by status | Resolution | | get_disputed_markets | Markets disputed during oracle resolution (high-signal events) | Resolution | | get_market_revisions | Moderator interventions and updates on market resolution | Resolution | | get_trader_profile | 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 | | get_trader_usdc_flows | USDC deposit/withdrawal history with direction filtering | Traders |

Polymarket REST API Tools (no Graph API key needed)

| Tool | Description | API | |------|-------------|-----| | search_markets | Search markets by text query with filters (active, closed, sort by volume/liquidity) | Gamma | | get_market_info | Get detailed market metadata by slug or condition ID | Gamma | | list_polymarket_events | Browse events (groups of related markets) with tag/status filters | Gamma | | get_polymarket_event | Get a single event with all its associated markets | Gamma | | get_live_prices | Real-time CLOB prices for outcome tokens (buy/sell, single or batch) | CLOB | | get_live_spread | Bid-ask spread + midpoint for assessing market liquidity | CLOB | | get_live_orderbook | Full order book (all resting bids and asks) for a token | CLOB | | get_price_history | Historical price time-series (1m to max interval, configurable fidelity) | CLOB | | get_last_trade | Last trade price for an outcome token | CLOB | | get_clob_market | CLOB market details: token IDs, live prices, min order/tick sizes | CLOB | | search_markets_enriched | Power tool: search + auto-enrich with live CLOB prices AND on-chain resolution status in one call | Gamma + CLOB + Graph |

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

| Name | IPFS Hash | Description | |------|-----------|-------------| | Main | QmdyCguLEisTtQFveEkvMhTH7UzjyhnrF9kpvhYeG4QX8a | Complete ecosystem data | | Beefy P&L | QmbHwcGkumWdyTK2jYWXV3vX4WyinftEGbuwi7hDkhPWqG | Comprehensive P&L tracking | | Slimmed P&L | QmZAYiMeZiWC7ZjdWepek7hy1jbcW3ngimBF9ibTiTtwQU | Minimal position data | | Activity | Qmf3qPUsfQ8et6E3QNBmuXXKqUJi91mo5zbsaTkQrSnMAP | Position management events | | Orderbook | QmVGA9vvNZtEquVzDpw8wnTFDxVjB6mavTRMTrKuUBhi4t | Order fill analytics | | Open Interest | QmbT2MmS2VGbGihiTUmWk6GMc2QYqoT9ZhiupUicYMWt6H | Per-market and global OI with hourly snapshots | | Resolution | QmZnnrHWCB1Mb8dxxXDxfComjNdaGyRC66W8derjn3XDPg | UMA oracle resolution lifecycle | | Traders | QmfT4YQwFfAi77hrC2JH3JiPF7C4nEn27UQRGNpSpUupqn | Per-trader event logs and USDC flows |

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.js

License

MIT

graph-polymarket-mcp