# Polymarket MCP Server
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
A powerful **MCP (Model Context Protocol) server** for querying [Polymarket](https://polymarket.com) prediction markets. Access real-time odds, market data, price history, and order books directly from your AI assistant.
## 🎯 What is This?
This MCP server enables AI assistants like **Claude**, **Cursor**, and other MCP-compatible tools to interact with Polymarket's prediction markets API. Query live market odds, track price movements, analyze order books, and explore markets by category — all through natural language.
## ✨ Features
| Tool | Description |
| ------------------------ | ----------------------------------------------------------- |
| `list_markets` | List and paginate through all Polymarket prediction markets |
| `search_markets` | Search markets by keyword (questions & descriptions) |
| `get_market` | Get detailed information about a specific market by ID |
| `get_event` | Fetch event details with all sub-markets grouped together |
| `get_events_by_category` | Filter markets by category (politics, crypto, sports, etc.) |
| `list_categories` | List all available market categories |
| `get_trending_markets` | Discover hot markets by volume or price movement |
| `get_price_history` | Historical price/odds data for any market |
| `get_order_book` | Real-time order book depth (bids & asks) |
## 📦 Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/poly-mcp.git
cd poly-mcp
# Install dependencies
npm install
# Build the project
npm run build
```
## 🚀 Usage
### Running the Server
```bash
# Production mode
npm start
# Development mode (with hot reload)
npm run dev
# MCP Inspector (for testing)
npm run client
```
### Adding to Cursor IDE
Add this to your Cursor MCP settings file (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"polymarket": {
"command": "node",
"args": ["/absolute/path/to/poly-mcp/dist/index.js"]
}
}
}
```
### Adding to Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"polymarket": {
"command": "node",
"args": ["/absolute/path/to/poly-mcp/dist/index.js"]
}
}
}
```
## 🛠️ Tools Reference
### `list_markets`
List prediction markets from Polymarket with pagination support.
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | ------------------------- |
| `limit` | number | 10 | Number of markets (1-100) |
| `active` | boolean | - | Filter by active status |
| `closed` | boolean | - | Filter by closed status |
| `offset` | number | 0 | Pagination offset |
**Example:** _"List 20 active markets on Polymarket"_
---
### `search_markets`
Search for markets by keyword matching questions and descriptions.
| Parameter | Type | Default | Description |
| --------- | ------- | ---------- | ------------------------ |
| `query` | string | _required_ | Search query |
| `limit` | number | 10 | Number of results (1-50) |
| `active` | boolean | - | Filter by active status |
| `closed` | boolean | - | Filter by closed status |
**Example:** _"Search for Bitcoin prediction markets"_
---
### `get_market`
Get detailed information about a specific market.
| Parameter | Type | Description |
| ----------- | ------ | ---------------------- |
| `market_id` | string | The market ID to fetch |
**Example:** _"Get details for market ID 0x..."_
---
### `get_event`
Fetch an event with all its sub-markets. Events group related markets together.
| Parameter | Type | Description |
| ------------- | ------- | ------------------------------------------------------ |
| `slug` | string | Event slug (e.g., `presidential-election-winner-2024`) |
| `event_id` | string | Event ID |
| `list_events` | boolean | List available events instead |
| `limit` | number | Number of events to list (default: 10) |
**Example:** _"Show me the presidential election event on Polymarket"_
---
### `get_events_by_category`
Filter prediction markets by category for focused exploration.
| Parameter | Type | Default | Description |
| ---------- | ------- | ---------- | --------------------------- |
| `category` | enum | _required_ | Category filter (see below) |
| `limit` | number | 10 | Number of events (1-50) |
| `active` | boolean | true | Filter by active status |
| `closed` | boolean | false | Filter by closed status |
**Available Categories:**
- `politics` — Elections, government, political events
- `crypto` — Cryptocurrency, blockchain, DeFi
- `sports` — NFL, NBA, Soccer, and more
- `world` — International relations, geopolitics
- `entertainment` — Music, TV, celebrities
- `economy` — GDP, markets, business
- `science` — Technology, AI, space, climate
- `legal` — Court cases, laws
- `racing` — F1, NASCAR, motorsports
**Example:** _"Show me politics markets on Polymarket"_
---
### `list_categories`
List all available categories for filtering markets.
**Example:** _"What categories are available on Polymarket?"_
---
### `get_trending_markets`
Discover trending markets sorted by activity metrics.
| Parameter | Type | Default | Description |
| --------- | ------ | ------------ | ------------------------ |
| `sort_by` | enum | `volume24hr` | Sort metric |
| `limit` | number | 10 | Number of markets (1-50) |
**Sort Options:**
- `volume24hr` — 24-hour trading volume
- `volume1wk` — Weekly trading volume
- `oneDayPriceChange` — 24-hour price movement
- `oneWeekPriceChange` — Weekly price movement
**Example:** _"Show me the hottest markets by 24h volume"_
---
### `get_price_history`
Get historical price/odds data for market analysis.
| Parameter | Type | Default | Description |
| --------------- | ------ | ---------- | ----------------------- |
| `market_id` | string | _required_ | Market ID |
| `outcome_index` | number | 0 | Outcome index (0 = Yes) |
| `interval` | enum | `1m` | Time range |
**Intervals:** `1d`, `1w`, `1m`, `3m`, `1y`, `max`
**Example:** _"Show price history for market 0x... over the past month"_
---
### `get_order_book`
Get real-time order book depth showing current bids and asks.
| Parameter | Type | Default | Description |
| --------------- | ------ | ---------- | ----------------------- |
| `market_id` | string | _required_ | Market ID |
| `outcome_index` | number | 0 | Outcome index (0 = Yes) |
**Example:** _"Show me the order book for market 0x..."_
## 💡 Example Queries
Once configured, you can ask your AI assistant:
- _"Show me politics markets with more than 50% odds for Yes"_
- _"What are the trending crypto markets right now?"_
- _"Search for Trump prediction markets"_
- _"Get the price history for the Bitcoin $100k market"_
- _"List all sports betting markets"_
- _"What's the order book depth for the presidential election market?"_
### Prompt Templates
Quick prompts to try with your AI assistant:
```
# Quick market check
What does Polymarket say about [TOPIC]? Show me the odds.
# Cross-source validation
News reports say [EVENT]. Check Polymarket and tell me if the
smart money agrees.
# Find opportunities
Find markets closing in the next 24 hours with 90%+ odds on one side.
```
## 🔧 Development
```bash
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build for production
npm run build
# Test with MCP Inspector
npm run client
```
## 📄 API Sources
This server uses the following Polymarket APIs:
- **Gamma API** (`gamma-api.polymarket.com`) — Market and event data
- **CLOB API** (`clob.polymarket.com`) — Order books and price history
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📜 License
MIT License - see [LICENSE](LICENSE) for details.
## 🔗 Links
- [Polymarket](https://polymarket.com) — The prediction market platform
- [Model Context Protocol](https://modelcontextprotocol.io) — MCP specification
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) — Official SDK
---
**Keywords:** Polymarket, MCP, Model Context Protocol, prediction markets, AI assistant, Claude, Cursor, betting odds, crypto markets, political betting, sports betting, market analysis, order book, price history
