# Polymarket MCP Server

**The simplest way to query Polymarket prediction-market data with AI agents.**

Built by [Polycool](https://polycoolapp.com) — track & copy top Polymarket traders in one tap.

[![PyPI](https://img.shields.io/pypi/v/polymarket-mcp.svg)](https://pypi.org/project/polymarket-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## What is this?

A lightweight **Model Context Protocol (MCP) server** that gives any AI agent instant access to [Polymarket](https://polymarket.com) prediction-market data — search markets, check probabilities, analyse liquidity, track price history, and more.

Built with [FastMCP](https://github.com/jlowin/fastmcp) in pure Python. Part of the [Polycool](https://polycoolapp.com) ecosystem.

## Why does this exist?

AI agents need **real-time data feeds** to be useful. Prediction markets are one of the best sources of crowd-sourced probability estimates on world events.

This project bridges the gap:

- **No trading.** Read-only market data.
- **No wallets.** No blockchain signing, no private keys.
- **No complexity.** Seven tools, zero configuration.

Just plug it into Claude Desktop, Cursor, or any MCP-compatible client and start asking questions about the future.

---

## Tools

| Tool | Description |
|------|-------------|
| `search_markets` | Full-text search across all markets (e.g. "Bitcoin", "NBA", "election") |
| `trending_markets` | Top markets ranked by 24-hour volume |
| `new_markets` | Most recently launched markets |
| `markets_closing_soon` | Markets resolving within N hours |
| `market_summary` | Detailed probability, volume, liquidity, spread & metadata |
| `market_orderbook` | Live orderbook with bids, asks, spread & last trade price |
| `market_price_history` | Historical price data with min, max, and % change over any time window |

---

## Quick Install

### One-Click Install for Cursor

Copy and paste this URL into your browser to install instantly:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=polymarket&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyItLXB5dGhvbiIsICIzLjExIiwgInBvbHltYXJrZXQtbWNwIl19
```

Cursor opens, prompts you to install — click "Install" and you're done. No cloning, no pip install.

### Install with `uvx`

```bash
uvx --python 3.11 polymarket-mcp
```

Downloads the package, installs dependencies in an isolated environment, starts the server. Nothing touches your system Python.

**Prerequisite:** [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

### Install with `pip`

```bash
pip install polymarket-mcp
polymarket-mcp
```

---

## Setup

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "uvx",
      "args": ["--python", "3.11", "polymarket-mcp"]
    }
  }
}
```

### Claude Desktop

Add to your config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "uvx",
      "args": ["--python", "3.11", "polymarket-mcp"]
    }
  }
}
```

Restart Claude Desktop. The Polymarket tools appear in the tool list.

---

## Example Prompts

Once connected, try asking your AI agent:

> "Show me the top 10 trending markets on Polymarket"

> "Find all markets about Bitcoin"

> "Which markets resolve in the next 24 hours?"

> "Give me a detailed summary of this market"

> "Show me the price history for this market over the last week"

> "What does the orderbook look like for this market?"

---

## Example Output

```json
{
  "market_id": "21742",
  "question": "Will Bitcoin exceed $100,000 by June 2026?",
  "probability": 0.72,
  "volume_24h": 245000,
  "volume_total": 8900000,
  "liquidity": 620000,
  "best_bid": 0.71,
  "best_ask": 0.73,
  "spread": 0.02,
  "category": "Crypto",
  "end_date": "2026-06-30T00:00:00Z",
  "active": true
}
```

---

## APIs Used

| API | Purpose |
|-----|---------|
| [Polymarket Gamma API](https://gamma-api.polymarket.com) | Market data, events, full-text search |
| [Polymarket CLOB API](https://clob.polymarket.com) | Orderbook, price history, last trade price |

Both APIs are **public and free**. No API key required.

---

## Built by Polycool

This MCP server is built and maintained by the [Polycool](https://polycoolapp.com) team.

**Polycool** lets you track and copy top Polymarket traders — insiders and smart wallets — in one tap.

- [polycoolapp.com](https://polycoolapp.com) — Web app
- [@polycoolapp_bot](https://t.me/polycoolapp_bot) — Telegram bot for instant alerts and copy-trading
- Backed by the **Polymarket Builder Program**

---

## License

MIT

---

*polymarket api, polymarket mcp server, prediction market api, polymarket data, polymarket analytics, polymarket python, polymarket ai agent, model context protocol, polycool, polymarket copy trading, polymarket telegram bot*
