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

Related MCP server: Polymarket MCP Server

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

Market Details

Pricing & Order Book

Analytics

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

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