📌Overview

Purpose: To provide access to real-time prediction market data via a standardized Model Context Protocol server interface with the PolyMarket API.

Overview: The PolyMarket MCP Server facilitates the retrieval of detailed prediction market information, including current prices, historical data, and market specifics through a user-friendly API, enhancing the decision-making process for users engaged in prediction markets.

Key Features:

Real-time Data Access: Provides current market prices and probabilities, enabling users to make informed predictions based on up-to-date information.
Comprehensive Market Information: Offers detailed insights into market categories, resolution dates, and descriptions, equipping users with essential knowledge of each market.
Historical Data Retrieval: Allows customization of historical price and volume data across various timeframes, supporting analysis and forecasting.
Robust Error Handling: Includes built-in management for rate limits and connectivity issues to ensure reliability during data retrieval.
Clean Data Formatting: Presents data in an easily consumable format, enhancing usability for developers and analysts alike.

PolyMarket MCP Server

A Model Context Protocol (MCP) server that provides access to prediction market data through the PolyMarket API. It implements a standardized interface for retrieving market information, prices, and historical data from prediction markets.

Features

Real-time prediction market data with current prices and probabilities
Detailed market information including categories, resolution dates, and descriptions
Historical price and volume data with customizable timeframes (1d, 7d, 30d, all)
Built-in error handling and rate limit management
Clean data formatting for easy consumption

Installation

Installing via Smithery

To install PolyMarket Predictions for Claude Desktop automatically via Smithery:

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

Claude Desktop Configuration Paths

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

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

Running Locally

Clone the repository and install dependencies:

pip install -e .

Create a .env file with your PolyMarket API key:

Key=your_api_key_here
Funder=poly market wallet address

Run the server in the polymarket-mcp repository:

uv run src/polymarket_mcp/server.py

To run the server inspector along with the server:

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

After connecting the Claude client with the MCP tool via the json file and installing the packages, Claude should recognize the server's MCP tools.

Available Tools

The server implements four tools:

get-market-info: Get detailed information about a specific prediction market
list-markets: List available prediction markets with filtering options
get-market-prices: Get current prices and trading information
get-market-history: Get historical price and volume data

get-market-info

Input Schema:

{
    "market_id": {
        "type": "string",
        "description": "Market ID or slug"
    }
}

Example Response:

Title: Example Market  
Category: Politics  
Status: Open  
Resolution Date: 2024-12-31  
Volume: $1,234,567.89  
Liquidity: $98,765.43  
Description: This is an example prediction market...
---

list-markets

Input Schema:

{
    "status": {
        "type": "string",
        "description": "Filter by market status",
        "enum": ["open", "closed", "resolved"]
    },
    "limit": {
        "type": "integer",
        "description": "Number of markets to return",
        "default": 10,
        "minimum": 1,
        "maximum": 100
    },
    "offset": {
        "type": "integer",
        "description": "Number of markets to skip (for pagination)",
        "default": 0,
        "minimum": 0
    }
}

Example Response:

Available Markets:

ID: market-123  
Title: US Presidential Election 2024  
Status: Open  
Volume: $1,234,567.89  
---

ID: market-124  
Title: Oscar Best Picture 2024  
Status: Open  
Volume: $234,567.89  
---

get-market-prices

Input Schema:

{
    "market_id": {
        "type": "string",
        "description": "Market ID or slug"
    }
}

Example Response:

Current Market Prices for US Presidential Election 2024

Outcome: Democratic  
Price: $0.6500  
Probability: 65.0%  
---

Outcome: Republican  
Price: $0.3500  
Probability: 35.0%  
---

get-market-history

Input Schema:

{
    "market_id": {
        "type": "string",
        "description": "Market ID or slug"
    },
    "timeframe": {
        "type": "string",
        "description": "Time period for historical data",
        "enum": ["1d", "7d", "30d", "all"],
        "default": "7d"
    }
}

Example Response:

Historical Data for US Presidential Election 2024  
Time Period: 7d

Time: 2024-01-20T12:00:00Z  
Price: $0.6500  
Volume: $123,456.78  
---

Time: 2024-01-19T12:00:00Z  
Price: $0.6300  
Volume: $98,765.43  
---

Error Handling

The server includes comprehensive error handling for:

Rate limiting (429 errors)
Invalid API keys (403 errors)
Invalid market IDs (404 errors)
Network connectivity issues
API timeout conditions (30-second timeout)
Malformed responses

Error messages are returned in a clear, human-readable format.

Prerequisites

Python 3.9 or higher
httpx version 0.24.0 or higher
mcp-core
python-dotenv version 1.0.0 or higher

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss.