Polymarket MCP Server

A Model Context Protocol (MCP) server that provides real-time access to Polymarket prediction market data. Browse, search, and analyze prediction markets directly from Claude, Cursor, or any MCP-compatible client.

No API key required — all endpoints are public and read-only.

Features

• Search prediction markets by keyword
• Browse events and markets with rich filtering (category, volume, liquidity, date)
• View real-time outcome probabilities and market details
• Analyze order book depth, bid-ask spreads, and price history
• Track top traders on the leaderboard and top position holders

---

Quick Start

Option 1: Local (stdio mode)

Use with Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "polymarket-mcp"]
    }
  }
}

Use with Claude Code:

claude mcp add polymarket -- npx -y polymarket-mcp

Use with Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "polymarket-mcp"]
    }
  }
}

Option 2: Remote Server (HTTP mode)

If you have a server running the MCP HTTP service, connect via URL:

{
  "mcpServers": {
    "polymarket": {
      "url": "http://YOUR_SERVER_IP:3000/mcp"
    }
  }
}

Or with Cloudflare Tunnel:

{
  "mcpServers": {
    "polymarket": {
      "url": "https://your-tunnel-domain.trycloudflare.com/mcp"
    }
  }
}

---

Server Deployment

1. Install & Build

git clone https://github.com/suy2014/polymarket-mcp.git
cd polymarket-mcp
npm install
npm run build

2. Run

Stdio mode (for local use):

node dist/index.js

HTTP mode (for remote access):

# Default port 3000
node dist/index.js --http

# Custom port
PORT=8080 node dist/index.js --http

# Or use environment variable
MCP_HTTP=1 PORT=3000 node dist/index.js

3. Production (pm2)

npm install -g pm2
PORT=3000 pm2 start dist/index.js --name polymarket-mcp -- --http
pm2 save
pm2 startup   # auto-start on reboot

4. Expose via Cloudflare Tunnel (optional)

If your server is behind a firewall or doesn't have a domain:

# Install cloudflared
curl -L -o cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x cloudflared

# Create tunnel (generates a public URL)
./cloudflared tunnel --url http://localhost:3000
# Output: https://xxx-xxx.trycloudflare.com

Users can then connect with the tunnel URL:

{
  "mcpServers": {
    "polymarket": {
      "url": "https://xxx-xxx.trycloudflare.com/mcp"
    }
  }
}

5. Health Check

curl http://localhost:3000/health
# {"status":"ok","sessions":0}

---

Available Tools (12)

Discovery & Search

Tool	Description
search_markets	Search markets/events by keyword (e.g. "Trump", "Bitcoin", "AI")
list_events	Browse events with filtering by tag, volume, liquidity, status
list_markets	Browse individual markets with sorting and filtering
list_tags	List all category tags (politics, crypto, sports, etc.)

Market Details

Tool	Description
get_event	Get event details with all associated markets and probabilities
get_market	Get single market details including condition ID and token IDs

Pricing & Order Book

Tool	Description
get_prices	Get current midpoint prices (probabilities) for tokens
get_spreads	Get bid-ask spreads to assess liquidity
get_price_history	Get historical price data (1h/6h/1d/1w/1m/all intervals)
get_orderbook	Get full order book with bid/ask depth

Analytics

Tool	Description
get_market_holders	Top position holders for a market
get_leaderboard	Trader rankings by PnL or volume

---

Example Conversations

"What are the hottest prediction markets right now?" → Calls list_events sorted by volume

"What's the probability of Bitcoin reaching $200k?" → Calls search_markets with query "Bitcoin 200k"

"Show me the price history for this market over the past week" → Calls get_price_history with interval "1w"

"How liquid is this market? Show me the order book" → Calls get_orderbook + get_spreads

"Who are the top traders on Polymarket?" → Calls get_leaderboard sorted by PnL

---

Tool Workflow

Most analysis flows follow this pattern:

search_markets / list_events     →  Find markets of interest
        ↓
get_event / get_market           →  Get details (condition_id, clobTokenIds)
        ↓
get_prices / get_price_history   →  Current & historical probabilities
get_orderbook / get_spreads      →  Liquidity analysis
get_market_holders               →  Position analysis

Key identifiers: condition_id is used for price history and holders. clobTokenIds are used for prices, spreads, and order books. Both come from get_market or get_event responses.

---

API Sources

API	Base URL	Used For
Gamma API	gamma-api.polymarket.com	Events, markets, tags, search
CLOB API	clob.polymarket.com	Order book, prices, spreads, history
Data API	data-api.polymarket.com	Holders, leaderboard

Requirements

• Node.js >= 18 (uses built-in fetch)
• No API keys needed

Development

git clone https://github.com/suy2014/polymarket-mcp.git
cd polymarket-mcp
npm install
npm run build
npm run dev    # watch mode

Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT