Polymarket MCP Server

A powerful MCP (Model Context Protocol) server for querying Polymarket 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

# 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

# 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):

{
  "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):

{
  "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

# 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 for details.

🔗 Links

• Polymarket — The prediction market platform
• Model Context Protocol — MCP specification
• MCP 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