name: graph-polymarket-mcp
version: 2.1.2
description: Query Polymarket prediction market data via The Graph subgraphs + Polymarket REST APIs (Gamma + CLOB) — 35 tools for market search, live prices, on-chain analytics, trader P&L, open interest, resolution status, and CLOB V2 builder attribution.
metadata:
clawdbot:
emoji: "🔮"
requires:
bins: ["node"]
env: ["GRAPH_API_KEY"]
primaryEnv: "GRAPH_API_KEY"
# Declared explicitly rather than left implicit: this server reads one env var and
# talks to three hosts, and nothing else. Anything outside this list is a bug.
capabilities:
env:
- name: GRAPH_API_KEY
purpose: "Authenticates subgraph queries to The Graph gateway. Sent only to gateway.thegraph.com; never logged, never forwarded to Polymarket or any other host."
required: false
network:
- host: gateway.thegraph.com
purpose: "Subgraph queries. Receives GRAPH_API_KEY."
- host: gamma-api.polymarket.com
purpose: "Public market metadata. No credentials sent."
- host: clob.polymarket.com
purpose: "Public prices and order books. No credentials sent."
filesystem: none
transports: ["stdio (default)", "sse (opt-in, --http)"]
Graph Polymarket MCP
Transport note. The default is stdio — no network surface, nothing listening. The optional --http SSE transport is unauthenticated: anyone who can reach the port can call every tool and spend your GRAPH_API_KEY quota. Bind it to localhost and front it with TLS and auth if it must be reachable.
Query Polymarket prediction market data via The Graph subgraphs and Polymarket REST APIs (Gamma + CLOB) — market search, live prices, order books, trader P&L, positions, open interest, resolution status, and trader profiles.
Try it
Polymarket REST API (no API key needed)
- search_markets — Search markets by text query with filters (active, closed, sort by volume/liquidity)
- get_market_info — Get detailed market metadata by slug or condition ID
- list_polymarket_events — Browse events (groups of related markets) with tag/status filters
- get_polymarket_event — Get a single event with all its associated markets
- get_live_prices — Real-time CLOB prices for outcome tokens (buy/sell, single or batch)
- get_live_spread — Bid-ask spread + midpoint for assessing market liquidity
- get_live_orderbook — Full order book (all resting bids and asks) for a token
- get_price_history — Historical price time-series (1m to max interval, configurable fidelity)
- get_last_trade — Last trade price for an outcome token
- get_clob_market — CLOB market details: token IDs, live prices, min order/tick sizes
- search_markets_enriched — Power tool: search + auto-enrich with live CLOB prices AND on-chain resolution status
The Graph Subgraphs (requires GRAPH_API_KEY)
- 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
- get_market_data — Get market/condition data with outcomes and resolution status
- get_global_stats — Platform stats: market counts, volume, fees, trades
- get_account_pnl — Trader P&L and performance metrics (winRate, profitFactor, maxDrawdown)
- get_top_traders — Leaderboard ranked by PnL, winRate, volume, or profitFactor
- get_daily_stats — Daily volume, fees, trader counts, and market activity
- get_market_positions — Top holders for a specific outcome token with their P&L
- get_user_positions — A user's current token positions
- get_recent_activity — Recent splits, merges, and redemptions
- get_orderbook_trades — Recent order fills with maker/taker filtering
- get_market_open_interest — Top markets ranked by USDC locked in positions
- get_oi_history — Hourly OI snapshots for a specific market
- get_global_open_interest — Total platform-wide open interest and market count
- get_market_resolution — UMA oracle resolution status with filtering
- get_disputed_markets — Markets disputed during oracle resolution
- get_market_revisions — Moderator interventions and updates on market resolution
- get_trader_profile — Full trader profile: first seen, CTF events, USDC flows
- get_trader_usdc_flows — USDC deposit/withdrawal history with direction filtering
- Runtime: Node.js >= 18 (runs via
npx) - Environment variables:
GRAPH_API_KEY (required for subgraph tools) — Free API key from The Graph Studio. Free tier: 100K queries/month.- REST API tools (search, prices, order books) work without any API key.
Install
GRAPH_API_KEY=your-key npx graph-polymarket-mcp
Get a free API key at The Graph Studio (free tier: 100K queries/month).
- Subgraph tools make GraphQL requests to The Graph Gateway (
gateway.thegraph.com) using your API key. - REST API tools query Polymarket's public endpoints (
gamma-api.polymarket.com and clob.polymarket.com) directly — no authentication needed. - Eight subgraphs are queried: Main, Beefy P&L, Slimmed P&L, Activity, Orderbook, Open Interest, Resolution, and Traders.
- No local database or persistent storage is used.
- The SSE transport (
--http / --http-only) starts a local HTTP server on port 3851 (configurable via MCP_HTTP_PORT env var).
| Endpoint | Data sent | Purpose |
|---|
gateway.thegraph.com | GraphQL queries with your API key | Queries 8 Polymarket subgraphs |
- Search and discover prediction markets by topic, category, or keyword
- Get real-time prices, order books, and spreads for any market
- Analyze price history and market trends
- Get platform-wide stats, volume, and market rankings
- Analyze trader P&L, performance metrics, and leaderboards
- Track open interest trends and market positions
- Monitor market resolution lifecycle and disputed markets
- Run custom GraphQL queries against 8 specialized Polymarket subgraphs