graph-polymarket-mcp

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)

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