kukapay/polymarket-predictions-mcp

An MCP server that delivers real-time market odds from Polymarket, enabling AI agents and analysts to access, compare, and act on decentralized prediction data.
Features
- **Event Retrieval**: Fetch Polymarket events with details (title, description, endDate, volume) and associated markets in a tabulated format.
- **Market Retrieval**: Retrieve markets with key fields (question, zipped outcomes and outcomePrices, endDate, volume, closed) in a table.
- **Event Search**: Search for events using Polymarket's /public-search endpoint with comprehensive query parameters.
- **Prompt Support**: Includes a prompt template for analyzing specific markets.
- **Formatted Outputs**: Uses tabulate for clean, readable table outputs and handles JSON parsing for outcomes and prices.
Installation
Prerequisites
- Python 3.10 or higher
- uv (recommended) or pip for dependency management
Setup
1. **Clone the Repository**:
2. **Install Dependencies**:
Using uv:
Or using pip:
3. **Install to Claude Desktop**:
Install the server as a Claude Desktop application:
Configuration file as a reference:
Replace /path/to/polymarket-predictions-mcp with your actual installation path.
Usage
The server exposes three tools and one prompt:
Tools
1. **get_events**:
Fetches a list of Polymarket events with details and their associated markets.
- **Parameters**:
- limit: Number of events (default: 10)
- offset: Pagination offset (default: 0)
- order: Fields to order by (e.g., volume,markets.volume)
- ascending: Sort order (default: False)
- id: List of event IDs
- slug: List of event slugs
- tag_id: Tag ID filter
- closed: Filter for closed events (default: False)
- **Output**: Formatted string with event details (title, description, endDate, volume) and a table of markets (question, closed, volume, outcomes, outcomePrices).
**Example**:
- **Prompt**
> Show me the top 2 Polymarket events by volume, including only open events, with their market details.
- **Sample Output**:
2. **get_markets**:
Fetches a list of Polymarket markets with specified fields.
- **Parameters**:
- limit: Number of markets (default: 10)
- offset: Pagination offset (default: 0)
- order: Fields to order by (e.g., volume)
- ascending: Sort order (default: False)
- id: List of market IDs
- slug: List of market slugs
- condition_ids: List of condition IDs
- closed: Filter for closed markets (default: False)
- **Output**: Table with question, options (zipped outcomes and outcomePrices), endDate, volume, and closed.
**Example**:
- **Prompt**:
> List the top 2 Polymarket markets by trading volume, showing only open markets with their outcomes and prices.
- **Sample Output**:
3. **search_events**:
Searches for events using the /public-search endpoint.
- **Parameters**:
- q: Search query (required)
- cache: Use cached results
- events_status: Filter by event status
- limit_per_type: Results per type (default: 10)
- page: Page number for pagination