0xchron-polymarket-mcp 0.1.0

Read-only Polymarket prediction market data for AI agents (MCP server).

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

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_user_positions	Open positions for a wallet address
get_user_performance	Portfolio value, P&L, volume, and leaderboard rank

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:

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

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.

Publishing to the MCP Registry

The MCP Registry hosts server metadata so clients can discover and install MCP servers. This project is set up for GitHub-based publishing under the name io.github.0xChron/polymarket-mcp.

1. Publish a package artifact

The registry stores metadata only — you must publish the server to a supported package registry first. Options:

PyPI (recommended for Python users):

1. Ensure this README contains the ownership marker (already included above as an HTML comment).
2. Publish to PyPI: uv build && uv publish
3. Users can then run with uvx 0xchron-polymarket-mcp after the package is available.

Docker (OCI):

1. Push the image to a public registry (e.g. Docker Hub or GHCR).

2. Add the registry label to your image:

   LABEL io.modelcontextprotocol.server.name="io.github.0xChron/polymarket-mcp"
   

2. Create server.json

Install the publisher CLI and generate a template:

brew install mcp-publisher
# or: curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

mcp-publisher init

Edit server.json — example for a PyPI package with streamable HTTP:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.0xChron/polymarket-mcp",
  "description": "Read-only Polymarket prediction market data for AI agents.",
  "repository": {
    "url": "https://github.com/0xChron/polymarket-mcp",
    "source": "github"
  },
  "version": "0.1.0",
  "packages": [
    {
      "registryType": "pypi",
      "registryBaseUrl": "https://pypi.org",
      "identifier": "0xchron-polymarket-mcp",
      "version": "0.1.0",
      "runtimeHint": "uvx",
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:8000/mcp"
      }
    }
  ]
}

For a Docker image, use "registryType": "oci" and set "identifier" to your image reference (e.g. ghcr.io/0xchron/polymarket-mcp:0.1.0).

The name in server.json must match the mcp-name in this README (PyPI) or the Docker label (OCI).

3. Authenticate and publish

mcp-publisher login github
mcp-publisher publish --dry-run   # validate first
mcp-publisher publish

With GitHub auth, the server name must start with io.github.0xChron/. See the registry quickstart for full details.

License

MIT — see LICENSE.