Metadata-Version: 2.4
Name: polymarket-mcp
Version: 0.1.0
Summary: The simplest MCP server for Polymarket prediction-market data
Project-URL: Homepage, https://github.com/YOUR_USERNAME/polymarket-mcp
Project-URL: Repository, https://github.com/YOUR_USERNAME/polymarket-mcp
Project-URL: Issues, https://github.com/YOUR_USERNAME/polymarket-mcp/issues
Author: Your Name
License-Expression: MIT
Keywords: ai-agents,mcp,model-context-protocol,polymarket,prediction-markets
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Polymarket MCP Server

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

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=polymarket&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyItLXB5dGhvbiIsICIzLjExIiwgInBvbHltYXJrZXQtbWNwIl19)
[![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, and more.

Built with [FastMCP](https://github.com/jlowin/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

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=polymarket&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyItLXB5dGhvbiIsICIzLjExIiwgInBvbHltYXJrZXQtbWNwIl19)

> 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`](https://docs.astral.sh/uv/) installed:

```bash
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`

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

---

## Usage with Cursor (manual config)

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

```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`

```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:

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

Or after cloning:

```bash
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:

```json
{
  "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](https://docs.astral.sh/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:

```bash
# 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:

```bash
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

```json
{
  "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](https://github.com/jlowin/fastmcp)** — Python framework for building MCP servers
- **[httpx](https://www.python-httpx.org/)** — Async HTTP client
- **[Pydantic](https://docs.pydantic.dev/)** — Data validation (used by FastMCP)
- **[Polymarket Gamma API](https://gamma-api.polymarket.com)** — 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
