# Polymarket MCP Server (read-only)

A read-only [MCP](https://modelcontextprotocol.io) server exposing Polymarket's public
prediction-market data. Search markets, read live odds and order books, pull historical
probability time-series, and inspect public wallet positions — all over **public,
unauthenticated** endpoints.

**Read-only by design.** No order placement, cancellation, signing, wallets, or private keys.
**No API keys, no environment variables, zero secrets.**

## Tools

| Tool | What it does |
|---|---|
| `polymarket_search` | Natural-language search across events / markets / tags. |
| `polymarket_list_markets` | Browse & filter markets (volume, liquidity, dates, tags). |
| `polymarket_get_market` | Full detail for one market by id, slug, or condition_id. |
| `polymarket_list_events` | Browse & filter events (groups of markets). |
| `polymarket_get_event` | Event detail with all child markets. |
| `polymarket_trending_markets` | What's hot right now (top markets by 24h volume). |
| `polymarket_get_live_price` | Freshest CLOB midpoint / bid / ask / spread for an outcome token. |
| `polymarket_get_order_book` | Live order book (top N levels) for an outcome token. |
| `polymarket_get_price_history` | Historical probability time-series for an outcome token. |
| `polymarket_get_user_positions` | Public current holdings for a wallet. |
| `polymarket_get_user_activity` | Recent on-chain activity for a wallet. |
| `polymarket_get_market_holders` | Top holders per outcome token for a market. |
| `polymarket_get_user_value` | Total portfolio value (USDC) for a wallet. |
| `polymarket_market_snapshot` | **Recommended:** live odds for one market in a single call. |

Every tool is annotated `readOnlyHint=True, openWorldHint=True`.

### Key concepts

- **Prices are probabilities.** Outcome prices are floats in `[0, 1]` (e.g. `0.41` = 41%).
  Tools also surface a human-readable `probability_pct`.
- **`token_id` vs `conditionId`.** CLOB pricing/book/history tools key on a **CLOB token id**
  (one per outcome, from a market's `clobTokenIds`) — not a slug or conditionId. The Data API's
  `condition_id` identifies the market itself.
- **Freshness.** Gamma discovery data can lag the live CLOB book by a few seconds. For the
  freshest odds use `polymarket_get_live_price` / `polymarket_market_snapshot` (CLOB midpoint).

## Install

Requires [`uv`](https://docs.astral.sh/uv/) (Python 3.11+).

Published to PyPI as [`mcp-polymarket`](https://pypi.org/project/mcp-polymarket/):

```bash
# Run on demand (no install):
uvx mcp-polymarket

# Or install as a persistent tool:
uv tool install mcp-polymarket
```

## Registration

No environment variables or API keys are required.

### Claude Code (CLI)

```bash
claude mcp add polymarket -- uvx mcp-polymarket
```

### Claude Desktop

Add to `claude_desktop_config.json`:

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

## Development

From a checkout of this repo:

```bash
uv sync                              # install deps
uv run mcp-polymarket                # run the server (stdio)
uv run python tests/smoke_test.py    # live smoke test (hits the public API)
```

Inspect the tool schemas and annotations:

```bash
npx @modelcontextprotocol/inspector uvx mcp-polymarket
```

## Publishing

Releases are published to PyPI automatically via
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens are
stored. The workflow in `.github/workflows/publish.yml` runs `uv build` and uploads
the artifacts whenever a **GitHub Release is published**. To cut a release:

```bash
# bump `version` in pyproject.toml, commit, then:
gh release create v0.1.0 --generate-notes
```

### Self-hosting over HTTP (optional)

In addition to the default stdio transport, the server can run over streamable-HTTP:

```bash
uv run polymarket-mcp --http --host 0.0.0.0 --port 8000
# served at http://<host>:<port>/mcp
```

## Evaluation

`evaluation.xml` contains stable, verifiable, read-only questions exercising multi-tool
workflows (search → market → price history → live price, etc.).