polymarket-mcp 0.1.0

The simplest MCP server for Polymarket prediction-market data

Polymarket MCP Server

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

---

What is this?

A lightweight Model Context Protocol (MCP) server that gives any AI agent instant access to Polymarket prediction-market data — search markets, check probabilities, analyse liquidity, and more.

Built with FastMCP in pure Python. ~500 lines of clean, hackable code.

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. Six tools, zero configuration.

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

---

Features

Tool	Description
search_markets	Search markets by keyword (e.g. "Bitcoin", "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 & metadata
market_orderbook	Live orderbook with bids, asks & spread

---

Example AI Prompts

Once connected, try asking your AI agent:

"Show me the top 10 trending markets on Polymarket"

"Find markets about Bitcoin"

"Which markets resolve in the next 24 hours?"

"Analyse the liquidity of market X"

"Compare the probabilities of these two markets"

---

Quick Install

One-Click Install for Cursor

Click the badge above — Cursor will prompt you to install the server. Done. No cloning, no pip install, nothing.

Or paste this URL into your browser:

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

Install with uvx (no clone needed)

If you have uv installed:

uvx --python 3.11 polymarket-mcp

That's it. uvx downloads the package, installs dependencies in an isolated environment, and starts the server. Nothing touches your system Python.

Install with pip

pip install polymarket-mcp
polymarket-mcp

---

Usage with Cursor (manual config)

If you prefer to configure manually, add to your .cursor/mcp.json:

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

---

Usage with Claude Desktop

Add this to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop. You'll see the Polymarket tools in the tool list.

---

Market Radar CLI

Want a quick terminal dashboard? Run:

uvx --python 3.11 --from polymarket-mcp polymarket-radar

Or after cloning:

python market_radar.py

Output:

🔥  TRENDING MARKETS (by 24h volume)

   1. Will Bitcoin hit $100k by end of 2026?
      prob 62.0%  |  vol $1.2M  |  liq $500K

⚡  HIGHEST LIQUIDITY MARKETS

   1. US Presidential Election 2028
      prob 51.0%  |  liq $2.1M

⏳  MARKETS CLOSING WITHIN 48 HOURS (3 found)

   1. Will ETH stay above $3000 this week?
      prob 78.5%  |  ends 2026-03-15T00

---

Project Structure

polymarket-mcp/
├── pyproject.toml              # Package config (makes pip/uvx work)
├── src/
│   └── polymarket_mcp/
│       ├── __init__.py
│       ├── server.py           # MCP server entry point
│       ├── tools.py            # 6 MCP tool definitions
│       ├── client.py           # Polymarket API wrapper
│       └── analysis.py         # Ranking, filtering, formatting helpers
├── server.py                   # Local dev entry point
├── market_radar.py             # CLI dashboard script
├── requirements.txt            # Dependencies
├── README.md
└── examples/
    └── example_queries.py      # Programmatic usage examples

---

How the One-Click Install Works

The Cursor deeplink encodes this config as base64 in the URL:

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

When a user clicks the badge:

1. Cursor opens and shows an install prompt
2. User clicks "Install"
3. Cursor adds the server to its MCP config
4. uvx auto-downloads the package from PyPI into an isolated env
5. Server starts — no manual setup required

Prerequisites for users: uv must be installed (curl -LsSf https://astral.sh/uv/install.sh | sh).

---

Publishing to PyPI

To make the one-click install work for everyone:

# Build the package
uv build

# Upload to PyPI (you need a PyPI account + API token)
uv publish

After publishing, anyone in the world can run:

uvx --python 3.11 polymarket-mcp

---

API Reference

Polymarket Gamma API

All market data comes from the public Gamma API:

GET https://gamma-api.polymarket.com/markets

Parameters: _limit, _sort, _order, active, closed, slug_contains

Polymarket CLOB API

Orderbook data comes from the CLOB API:

GET https://clob.polymarket.com/book?token_id={token_id}

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

---

Example Tool Output

{
  "market_id": "0x1234...abcd",
  "question": "Will Bitcoin exceed $100,000 by December 2026?",
  "probability": 0.62,
  "volume_24h": 120000,
  "volume_total": 5400000,
  "liquidity": 500000,
  "category": "crypto",
  "end_date": "2026-12-01T00:00:00Z",
  "active": true,
  "slug": "will-bitcoin-exceed-100000-by-december-2026"
}

---

Ideas for Contributors

Here are three simple improvements you could add:

1. Probability Change Tracker — Store snapshots and show how probabilities moved over the last 24h / 7d.
2. Trending Categories — Group markets by category and surface which categories are getting the most volume.
3. Market Sentiment Scoring — Combine probability + volume momentum + liquidity depth into a single "heat" score.

---

Tech Stack

• FastMCP — Python framework for building MCP servers
• httpx — Async HTTP client
• Pydantic — Data validation (used by FastMCP)
• Polymarket Gamma API — Public prediction market data

---

License

MIT — do whatever you want with it.

---

Keywords

polymarket api, polymarket data, polymarket analytics, polymarket mcp server, prediction market api, polymarket python, polymarket ai agent, model context protocol polymarket, mcp server prediction markets