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.

!GitHub License !Python Version !Status

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

Clone the Repository:

   git clone https://github.com/kukapay/polymarket-predictions-mcp.git
   cd polymarket-predictions-mcp

Install Dependencies:

Using uv: ``bash uv sync ``

Or using pip: ``bash pip install mcp[cli] httpx tabulate ``

Install to Claude Desktop:

Install the server as a Claude Desktop application: ``bash uv run mcp install main.py --name "Polymarket Predictions" ``

Configuration file as a reference:

    {
       "mcpServers": {
           "Polymarket Predictions": {
               "command": "uv",
               "args": [ "--directory", "/path/to/polymarket-predictions-mcp", "run", "main.py" ]
           }
       }
    }

Replace /path/to/polymarket-predictions-mcp with your actual installation path.

Usage

The server exposes three tools and one prompt:

Tools

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:

     ## US Presidential Election 2024

     Closed: False | End Date: 2024-11-05 | Volume: $1000000

     Predict the outcome of the 2024 US Presidential Election...

     Markets:
     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
     | Question                                         | Closed   | Volume    | Outcomes          | Outcome Prices    |
     +==================================================+==========+===========+===================+===================+
     | Who will win the 2024 US Presidential Election?  | False    | $500000   | Biden, Trump      | 0.45, 0.55       |
     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
     | Will Biden win the 2024 election?               | False    | $200000   | Yes, No           | 0.40, 0.60       |
     +--------------------------------------------------+----------+-----------+-------------------+-------------------+

     ## Super Bowl LVIII

     Closed: True | End Date: 2024-02-11 | Volume: $500000

     Predict outcomes related to Super Bowl LVIII...

     Markets:
     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
     | Question                                         | Closed   | Volume    | Outcomes          | Outcome Prices    |
     +==================================================+==========+===========+===================+===================+
     | Who will win Super Bowl LVIII?                  | True     | $300000   | Chiefs, 49ers     | 0.60, 0.40       |
     +--------------------------------------------------+----------+-----------+-------------------+-------------------+

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:

     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
     | Question                                         | Options                 | End Date            | Volume    | Closed   |
     +==================================================+=========================+=====================+===========+==========+
     | Who will win the 2024 US Presidential Election?  | {"Biden": 0.45, "Trump": 0.55} | 2024-11-05 | $500000   | False    |
     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
     | Will Bitcoin reach $100K by end of 2024?        | {"Yes": 0.30, "No": 0.70} | 2024-12-31     | $200000   | False    |
     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+

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
events_tag: List of event tags
keep_closed_markets: Number of closed markets
sort: Field to sort by
ascending: Sort order
search_tags: Include tags in search
search_profiles: Include profiles in search
recurrence: Filter by recurrence type
exclude_tag_id: List of tag IDs to exclude
optimized: Use optimized search
Output: Formatted string with event details and markets tables, similar to get_events.

Example:

Prompt:

Search for Polymarket events about 'Bitcoin', filtering for active events with the 'crypto' tag, sorted by volume in ascending order.

Sample Output: (Similar format to get_events output, with Bitcoin-related events and markets)

Prompt

analyze_market:

A prompt template for analyzing a specific market by slug, encouraging use of tools to fetch details and provide insights on probabilities, volume, and outcomes.

Example:

Prompt:

Analyze the Polymarket prediction market for 'us-presidential-election-2024' and provide insights on its probabilities, trading volume, and potential outcomes.

Command:

     analyze_market(market_slug="us-presidential-election-2024")

License

This project is licensed under the MIT License. See the LICENSE file for details.

polymarket-predictions-mcp