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:

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

2. Install Dependencies: Using uv:

   uv sync
   

   Or using pip:

   pip install mcp[cli] httpx tabulate
   

3. Install to Claude Desktop:

   Install the server as a Claude Desktop application:

   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

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:

     ## 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       |
     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
     

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:

     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
     | 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    |
     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
     

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
     • 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.