0xchron-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.

Tools

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

Requirements

• Python 3.12+
• uv (recommended) or Docker

Quick start

Clone the repo, install dependencies, and start the server:

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

The server listens on streamable HTTP at http://127.0.0.1:8000/mcp.

Verify it is running with the MCP Inspector:

make inspector

Connect the inspector 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, then point your client at the /mcp endpoint.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-scoped):

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

Restart Cursor (or reload the window) after saving. The server must be running before the client connects.

Claude Desktop / other HTTP clients

Any MCP client that supports streamable HTTP can connect to the same URL. Refer to your client's documentation for remote server configuration.

Example agent prompts

Once connected, an agent can call tools naturally:

• "Search Polymarket for active markets about Bitcoin ETFs"
• "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…?"

Docker

Build and run the container:

make build
docker run --rm -p 8000:8000 -e FASTMCP_HOST=0.0.0.0 polymarket-mcp

FASTMCP_HOST=0.0.0.0 is required so the server accepts connections from outside the container. Then connect your MCP client to http://localhost:8000/mcp.

Configuration

Optional environment variables override API endpoints and server settings:

Development

make run        # Start the server
make test       # Run tests
make inspector  # Open MCP Inspector
make build      # Build Docker image

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

License

MIT — see LICENSE.