polymarket-mcp

Polymarket MCP

MCP server that exposes read-only Polymarket prediction market data to AI agents. Tools wrap Polymarket's public Gamma (market discovery) and Data (positions, portfolio, leaderboard) APIs. There is no CLOB integration — this server cannot place trades or read order books.

<!-- mcp-name: io.github.0xChron/polymarket-mcp -->

Tools

| Tool | Description | |------|-------------| | search_markets | Search markets by title or description | | get_market_details | Full details for a single market (by slug or Polymarket URL) | | get_trending_markets | Trending events ranked by volume, liquidity, or competitiveness | | get_market_holders | Top holders per outcome for a market (by condition ID, slug, or URL) | | get_leaderboard | Top traders ranked by P&L or volume | | get_user_positions | Open positions for a wallet address | | get_user_performance | Portfolio value, P&L, volume, and leaderboard rank for one wallet |

All tools return markdown formatted for agent consumption. No API keys or wallet signing are required.

Resources

Static reference context (no API calls). Attach in MCP clients or read via Inspector.

| URI | Description | |-----|-------------| | polymarket://glossary | Event, market, slug, conditionId, and wallet terminology | | polymarket://categories | Leaderboard categories, time periods, and tag slugs | | polymarket://tool-guide | When to use each tool and chaining workflows |

Prompts

User-triggered workflow templates that orchestrate tools:

| Prompt | Description | |--------|-------------| | research_market | Market details → holders → research summary (slug or market_link) | | compare_traders | Side-by-side performance and positions for two wallets | | scan_trending | Trending events scan with optional tag_slug and limit |

Requirements

• Python 3.12+
• uv (recommended) or Docker
• Node.js (optional, only for MCP Inspector)

Quick start

This server uses streamable HTTP at http://127.0.0.1:8000/mcp. Start the server first, then connect your MCP client to that URL.

git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
uv sync
uv run polymarket-mcp

On Windows, use the same commands in PowerShell, Command Prompt, or Git Bash. Leave the terminal open while your MCP client is connected.

Docker

Works the same on all platforms if Docker Desktop is installed:

git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
docker build -t polymarket-mcp .
docker run --rm -p 8000:8000 -e FASTMCP_HOST=0.0.0.0 polymarket-mcp

FASTMCP_HOST=0.0.0.0 lets the server accept connections from outside the container.

Verify the server

Open MCP Inspector in another terminal:

npx -y @modelcontextprotocol/inspector

Connect to http://localhost:8000/mcp using the Streamable HTTP transport.

Connect from an MCP client

This server uses the streamable-http transport (not stdio). Start the server first (see Quick start), then add the config below to your MCP client.

Claude Desktop

Go to Claude → Settings → Developer → Edit Config to open claude_desktop_config.json, then include the following:

{
  "mcpServers": {
    "polymarket": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

If you already have other MCP servers configured, add the "polymarket" entry inside your existing mcpServers object instead of replacing the whole file.

Config file location if you prefer to edit it manually:

| Platform | Path | |----------|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Save the file and fully quit and restart Claude Desktop. The server must be running in a terminal before you start a new chat.

Cursor

Go to Settings → Tools & MCP → New MCP Server to open ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json), then add the same polymarket entry:

{
  "mcpServers": {
    "polymarket": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Restart Cursor after saving.

Example agent prompts

Once connected, an agent can call tools naturally:

• "Search Polymarket for active markets about Bitcoin ETFs"
• "What are the trending markets right now?"
• "Who are the top holders of the Trump election market?"
• "Show the all-time P&L leaderboard for crypto traders"
• "Get details for https://polymarket.com/event/will-bitcoin-hit-100k"
• "Show open positions for wallet 0x…"
• "What is the all-time P&L and leaderboard rank for 0x…?"

In MCP Inspector, try the Prompts tab (e.g. research_market) or read Resources for the glossary and tool guide.

Configuration

Optional environment variables override API endpoints and server settings.

macOS / Linux / Git Bash

export FASTMCP_HOST=0.0.0.0
export FASTMCP_PORT=8000
uv run polymarket-mcp

Windows (PowerShell)

$env:FASTMCP_HOST = "0.0.0.0"
$env:FASTMCP_PORT = "8000"
uv run polymarket-mcp

| Variable | Default | Description | |----------|---------|-------------| | GAMMA_URL | https://gamma-api.polymarket.com | Gamma API base URL | | DATA_URL | https://data-api.polymarket.com | Data API base URL | | DEFAULT_TIMEOUT | 15 | HTTP request timeout (seconds) | | FASTMCP_HOST | 127.0.0.1 | Bind address (0.0.0.0 for Docker) | | FASTMCP_PORT | 8000 | Listen port |

Development

uv run polymarket-mcp          # Start the server
uv run pytest                  # Run tests
npx -y @modelcontextprotocol/inspector   # Open MCP Inspector
docker build -t polymarket-mcp .         # Build Docker image

On macOS/Linux, make run, make test, and similar shortcuts in the Makefile wrap the same commands.

See docs/PROJECT_KNOWLEDGE_BASE.md for architecture, conventions, and how to add new tools.

License

MIT — see LICENSE.