# 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](https://img.shields.io/github/license/kukapay/polymarket-predictions-mcp) 
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
![Status](https://img.shields.io/badge/status-active-brightgreen.svg)

## 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](https://docs.astral.sh/uv/) (recommended) or `pip` for dependency management

### Setup

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/kukapay/polymarket-predictions-mcp.git
   cd polymarket-predictions-mcp
   ```

2. **Install Dependencies**:
   Using `uv`:
   ```bash
   uv sync
   ```

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

3. **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:

    ```json
    {
       "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**:
     ```bash
     analyze_market(market_slug="us-presidential-election-2024")
     ```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.