Polymarket MCP Server by pab1it0 - MCP Server

Polymarket MCP Server

A Model Context Protocol (MCP) server for Polymarket's Gamma Markets API.

This provides access to Polymarket's prediction markets and market data through standardized MCP interfaces, allowing AI assistants to query market data and analyze prediction markets.

Features

Market and Event data access
- List all available markets and events with extensive filtering options
- Get detailed market and event information
- Search markets by keyword
- Get order book data
- View recent trades
- Get historical market data
Docker containerization support
Provide interactive tools for AI assistants

The list of tools is configurable, so you can choose which tools you want to make available to the MCP client. This is useful if you don't use certain functionality or if you don't want to take up too much of the context window.

Usage with Claude Desktop

Docker Setup

To use the containerized server with Claude Desktop, add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "polymarket": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GAMMA_API_URL",
        "-e", "GAMMA_REQUIRES_AUTH",
        "polymarket-mcp-server"
      ],
      "env": {
        "GAMMA_API_URL": "https://gamma-api.polymarket.com",
        "GAMMA_REQUIRES_AUTH": "false"
      }
    }
  }
}

Note: You'll need to build the Docker image first with docker build -t polymarket-mcp-server .

UV Setup (Alternative Method)

If you prefer not to use Docker, you can use uv to run the server directly:

Create and configure a .env file in the project root directory:

# Copy the template
cp .env.template .env

# Edit the file to add your configuration
nano .env

Example .env content:

# Polymarket Gamma API Configuration
GAMMA_API_URL=https://gamma-api.polymarket.com
GAMMA_REQUIRES_AUTH=false

Add the server configuration to your Claude Desktop configuration:

{
  "mcpServers": {
    "polymarket": {
      "command": "/usr/local/bin/uv",  // Use the full path to your uv installation
      "args": [
        "run",
        "-m", "polymarket_mcp_server.main"
      ],
      "cwd": "<full path to polymarket-mcp directory>",
      "env": {
        "GAMMA_API_URL": "https://gamma-api.polymarket.com",
        "GAMMA_REQUIRES_AUTH": "false"
      }
    }
  }
}

Note: If you see Error: spawn uv ENOENT in Claude Desktop, you may need to specify the full path to uv or set the environment variable NO_UV=1 in the configuration.

Development

Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.

This project uses uv to manage dependencies. Install uv following the instructions for your platform:

curl -LsSf https://astral.sh/uv/install.sh | sh

You can then create a virtual environment and install the dependencies with:

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Environment Variables Support

The server loads environment variables from a .env file in the project root directory if present. Copy .env.template to .env and adjust the values as needed.

Project Structure

The project has been organized with a src directory structure:

polymarket-mcp/
├── src/
│   └── polymarket_mcp_server/
│       ├── __init__.py      # Package initialization
│       ├── server.py        # MCP server implementation
│       └── main.py          # Main application logic
├── Dockerfile               # Docker configuration
├── .dockerignore            # Docker ignore file
├── .env.template            # Template for environment variables
├── pyproject.toml           # Project configuration
└── README.md                # This file

Testing

The project includes a comprehensive test suite that ensures functionality and helps prevent regressions.

Run the tests with pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Tests are organized into:

Server functionality tests
Main application tests
Error handling tests

When adding new features, please also add corresponding tests.

Available Tools

Tool	Category	Description
`get_markets`	Market Data	Get a list of all available markets with comprehensive filtering options
`get_market_by_id`	Market Data	Get detailed information about a specific market
`get_order_book`	Market Data	[EXPERIMENTAL] Get the current order book for a market
`get_recent_trades`	Market Data	[EXPERIMENTAL] Get latest trades for a market
`get_market_history`	Market Data	[EXPERIMENTAL] Get historical market data
`search_markets`	Market Data	Search for markets by keyword using slug filtering
`get_events`	Event Data	Get a list of all available events with comprehensive filtering options
`get_event_by_id`	Event Data	Get detailed information about a specific event