PolyMarket MCP Server

How to use

Use an MCP client to interact with the PolyMarket MCP Server and retrieve data through the defined tools. You can fetch detailed information about a specific market, list markets with filters, obtain current prices and probabilities, and pull historical price and volume data for chosen timeframes. Each tool returns structured data that you can feed into dashboards, analytics, or trading strategies.

How to install

Prerequisites you need before starting:

- Python 3.9 or higher

- httpx>=0.24.0

- mcp-core

- python-dotenv>=1.0.0

How to install

Option A — Install via Smithery to enable Claude Desktop integration

npx -y @smithery/cli install polymarket_mcp --client claude

Run and configure locally

Step-by-step run flow you can follow to start the MCP server locally.

# 1) Clone the polymarket-mcp repository
# (Replace with your preferred path)
# git clone https://example.com/berlinbra/polymarket-mcp.git

# 2) Install the Python package in editable mode
uv pip install -e .

# 3) Run the MCP server
uv run src/polymarket_mcp/server.py

# Optional: run the inspector alongside the server
npx @modelcontextprotocol/inspector uv --directory C:\Users\{INSERT_USER}\YOUR\PATH\TO\polymarket-mcp run src/polymarket_mcp/server.py

# 4) Create a .env file with your PolyMarket API credentials
# Key=your_api_key_here
# Funder=poly market wallet address

MCP server configuration (environment and command)

The server can be started using an explicit MCP config snippet. This config runs the MCP server via uv with a specified working directory and starts the polymarket-mcp service. The environment must include your PolyMarket API key and wallet address.

{
  "mcpServers": {
    "polymarket_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/{INSERT_USER}/YOUR/PATH/TO/polymarket-mcp",
        "run",
        "polymarket-mcp" // or src/polymarket_mcp/server.py
      ],
      "env": {
        "KEY": "<insert poly market api key>",
        "FUNDER": "<insert polymarket wallet address>"
      }
    }
  }
}

Environment variables for the MCP server

The server requires the following environment variables. Provide actual values or placeholders where appropriate.

KEY=your_api_key_here
Funder=poly market wallet address

Starting the server with a client

After wiring up the MCP client to your environment, start the server using the command shown in the run steps above. The server will expose the four tools described below and will handle common errors such as rate limiting and invalid requests.

Notes and troubleshooting

- If you encounter rate limiting, ensure you respect API limits and retry with backoff. - If your API key is invalid, verify you pasted the correct KEY value in your .env file. - If a market ID is invalid, double-check the market slug you are querying. - Ensure connectivity to PolyMarket endpoints; verify network access and firewall rules. - The server includes a 30-second timeout for API calls; adjust as needed if your network is slow.

Tools provided by the PolyMarket MCP Server

The server implements four tools to access data programmatically.

• get-market-info: Retrieve detailed information about a specific prediction market
• list-markets: List available markets with optional status/offset/limit filters
• get-market-prices: Get current prices and probabilities for a market
• get-market-history: Retrieve historical price and volume data for a market across timeframes

get-market-info

Fetches detailed information about a single market by its ID or slug.

list-markets

Returns a list of markets with optional filters like status, limit, and offset for pagination.

get-market-prices

Provides current prices and probabilities for each outcome within a market.

get-market-history

Returns historical price and volume data for a market across selected timeframes.