Polymarket Predictions MCP

1# Polymarket Predictions MCP
2 
3An MCP server that delivers real-time market odds from Polymarket, enabling AI agents and analysts to access, compare, and act on decentralized prediction data.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/polymarket-predictions-mcp) 
6![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- **Event Retrieval**: Fetch Polymarket events with details (`title`, `description`, `endDate`, `volume`) and associated markets in a tabulated format.
12- **Market Retrieval**: Retrieve markets with key fields (`question`, zipped `outcomes` and `outcomePrices`, `endDate`, `volume`, `closed`) in a table.
13- **Event Search**: Search for events using Polymarket's `/public-search` endpoint with comprehensive query parameters.
14- **Prompt Support**: Includes a prompt template for analyzing specific markets.
15- **Formatted Outputs**: Uses `tabulate` for clean, readable table outputs and handles JSON parsing for outcomes and prices.
16 
17## Installation
18 
19### Prerequisites
20 
21- Python 3.10 or higher
22- [uv](https://docs.astral.sh/uv/) (recommended) or `pip` for dependency management
23 
24### Setup
25 
261. **Clone the Repository**:
27   ```bash
28   git clone https://github.com/kukapay/polymarket-predictions-mcp.git
29   cd polymarket-predictions-mcp
30   ```
31 
322. **Install Dependencies**:
33   Using `uv`:
34   ```bash
35   uv sync
36   ```
37 
38   Or using `pip`:
39   ```bash
40   pip install mcp[cli] httpx tabulate
41   ```
42 
433. **Install to Claude Desktop**:
44 
45    Install the server as a Claude Desktop application:
46    ```bash
47    uv run mcp install main.py --name "Polymarket Predictions"
48    ```
49 
50    Configuration file as a reference:
51 
52    ```json
53    {
54       "mcpServers": {
55           "Polymarket Predictions": {
56               "command": "uv",
57               "args": [ "--directory", "/path/to/polymarket-predictions-mcp", "run", "main.py" ]
58           }
59       }
60    }
61    ```
62    Replace `/path/to/polymarket-predictions-mcp` with your actual installation path.
63 
64## Usage
65 
66The server exposes three tools and one prompt:
67 
68### Tools
69 
701. **`get_events`**:
71   Fetches a list of Polymarket events with details and their associated markets.
72   - **Parameters**:
73     - `limit`: Number of events (default: 10)
74     - `offset`: Pagination offset (default: 0)
75     - `order`: Fields to order by (e.g., `volume,markets.volume`)
76     - `ascending`: Sort order (default: `False`)
77     - `id`: List of event IDs
78     - `slug`: List of event slugs
79     - `tag_id`: Tag ID filter
80     - `closed`: Filter for closed events (default: `False`)
81   - **Output**: Formatted string with event details (`title`, `description`, `endDate`, `volume`) and a table of markets (`question`, `closed`, `volume`, `outcomes`, `outcomePrices`).
82 
83   **Example**:
84   - **Prompt**
85      > Show me the top 2 Polymarket events by volume, including only open events, with their market details.
86   
87   - **Sample Output**:
88     ```
89     ## US Presidential Election 2024
90 
91     Closed: False | End Date: 2024-11-05 | Volume: $1000000
92 
93     Predict the outcome of the 2024 US Presidential Election...
94 
95     Markets:
96     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
97     | Question                                         | Closed   | Volume    | Outcomes          | Outcome Prices    |
98     +==================================================+==========+===========+===================+===================+
99     | Who will win the 2024 US Presidential Election?  | False    | $500000   | Biden, Trump      | 0.45, 0.55       |
100     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
101     | Will Biden win the 2024 election?               | False    | $200000   | Yes, No           | 0.40, 0.60       |
102     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
103 
104     ## Super Bowl LVIII
105 
106     Closed: True | End Date: 2024-02-11 | Volume: $500000
107 
108     Predict outcomes related to Super Bowl LVIII...
109 
110     Markets:
111     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
112     | Question                                         | Closed   | Volume    | Outcomes          | Outcome Prices    |
113     +==================================================+==========+===========+===================+===================+
114     | Who will win Super Bowl LVIII?                  | True     | $300000   | Chiefs, 49ers     | 0.60, 0.40       |
115     +--------------------------------------------------+----------+-----------+-------------------+-------------------+
116     ```
117 
1182. **`get_markets`**:
119   Fetches a list of Polymarket markets with specified fields.
120   - **Parameters**:
121     - `limit`: Number of markets (default: 10)
122     - `offset`: Pagination offset (default: 0)
123     - `order`: Fields to order by (e.g., `volume`)
124     - `ascending`: Sort order (default: `False`)
125     - `id`: List of market IDs
126     - `slug`: List of market slugs
127     - `condition_ids`: List of condition IDs
128     - `closed`: Filter for closed markets (default: `False`)
129   - **Output**: Table with `question`, `options` (zipped `outcomes` and `outcomePrices`), `endDate`, `volume`, and `closed`.
130 
131   **Example**:
132   - **Prompt**: 
133     > List the top 2 Polymarket markets by trading volume, showing only open markets with their outcomes and prices.
134     
135   - **Sample Output**:
136     ```
137     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
138     | Question                                         | Options                 | End Date            | Volume    | Closed   |
139     +==================================================+=========================+=====================+===========+==========+
140     | Who will win the 2024 US Presidential Election?  | {"Biden": 0.45, "Trump": 0.55} | 2024-11-05 | $500000   | False    |
141     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
142     | Will Bitcoin reach $100K by end of 2024?        | {"Yes": 0.30, "No": 0.70} | 2024-12-31     | $200000   | False    |
143     +--------------------------------------------------+-------------------------+---------------------+-----------+----------+
144     ```
145 
1463. **`search_events`**:
147   Searches for events using the `/public-search` endpoint.
148   - **Parameters**:
149     - `q`: Search query (required)
150     - `cache`: Use cached results
151     - `events_status`: Filter by event status
152     - `limit_per_type`: Results per type (default: 10)
153     - `page`: Page number for pagination
154     - `events_tag`: List of event tags
155     - `keep_closed_markets`: Number of closed markets
156     - `sort`: Field to sort by
157     - `ascending`: Sort order
158     - `search_tags`: Include tags in search
159     - `search_profiles`: Include profiles in search
160     - `recurrence`: Filter by recurrence type
161     - `exclude_tag_id`: List of tag IDs to exclude
162     - `optimized`: Use optimized search
163   - **Output**: Formatted string with event details and markets tables, similar to `get_events`.
164 
165   **Example**:
166   - **Prompt**: 
167     > Search for Polymarket events about 'Bitcoin', filtering for active events with the 'crypto' tag, sorted by volume in ascending order.
168   
169   - **Sample Output**: (Similar format to `get_events` output, with Bitcoin-related events and markets)
170 
171### Prompt
172 
173- **`analyze_market`**:
174   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.
175 
176   **Example**:
177   - **Prompt**: 
178     > Analyze the Polymarket prediction market for 'us-presidential-election-2024' and provide insights on its probabilities, trading volume, and potential outcomes.
179     
180   - **Command**:
181     ```bash
182     analyze_market(market_slug="us-presidential-election-2024")
183     ```
184 
185## License
186 
187This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
188 
189