polymarket-blade-mcp

Polymarket prediction market data — events, markets, orderbooks, prices, analytics.

Token-efficient, rate-limited MCP server for the Sidereal platform.

Why another Polymarket MCP?

Feature polymarket-blade-mcp prediction-mcp IQAIcom caiovicentino
Tools 22 12 19 45
Trading Write gates (v2) No Ungated Safety limits
Token efficiency Pipe-delimited, batching Cache + scoring Raw JSON Text formatting
Rate limiting Per-endpoint token buckets No No Configurable
Tests 99 5,767 lines Zero 3,688 lines
Type safety mypy strict TypeScript TypeScript Pydantic
Auth required None (public APIs) None (PM) / API key (Kalshi) Wallet key Wallet key
Sidereal marketplace Certified Community N/A N/A
License MIT MIT MIT MIT

What this MCP covers

Three Polymarket APIs, all public (no credentials):

  • Gamma API — events, markets, tags, search, sports (discovery)
  • CLOB API — orderbooks, prices, midpoints, spreads, price history (pricing)
  • Data API — open interest, top holders, leaderboard, volume (analytics)

Quick Start

Claude Code / Claude Desktop

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

From source

git clone https://github.com/Groupthink-dev/polymarket-blade-mcp
cd polymarket-blade-mcp
make install-dev
make run

Configuration

All optional — the server works with zero configuration.

Variable Default Description
POLYMARKET_GAMMA_HOST https://gamma-api.polymarket.com Override Gamma API host
POLYMARKET_CLOB_HOST https://clob.polymarket.com Override CLOB API host
POLYMARKET_DATA_HOST https://data-api.polymarket.com Override Data API host
POLYMARKET_MCP_TRANSPORT stdio Transport: stdio or http
POLYMARKET_MCP_HOST 0.0.0.0 HTTP transport bind address
POLYMARKET_MCP_PORT 8082 HTTP transport port
POLYMARKET_MCP_API_TOKEN (none) Bearer token for HTTP auth
POLYMARKET_WRITE_ENABLED false Enable write operations (v2)

Tool Reference

System (1)

Tool Description
pm_status API health + rate-limit stats

Discovery (8)

Tool Description
pm_events List/filter events (active, tag, limit, offset, order)
pm_event Event detail by ID or slug
pm_markets List/filter markets
pm_market Market detail by ID or slug
pm_search Keyword search across events + markets
pm_categories List tags/categories
pm_trending Featured/sampling markets
pm_sports Sports categories

Pricing (7)

Tool Description
pm_orderbook Order book with configurable depth (default 5)
pm_price Best price for a token (BUY/SELL side)
pm_prices_batch Batch prices for up to 20 tokens
pm_spread Bid-ask spread
pm_price_history Historical prices (fidelity: 1/5/60/360/1440 min)
pm_last_trade Last trade price
pm_tick_size Minimum tick size (0.1/0.01/0.001/0.0001)

Analytics (4)

Tool Description
pm_open_interest Open interest for tokens
pm_top_holders Top holders for a market
pm_leaderboard Trader rankings by profit
pm_volume Live event volume

Batch (2)

Tool Description
pm_orderbooks_batch Batch orderbooks for up to 10 tokens
pm_spreads_batch Batch spreads for up to 20 tokens

Security

  • Read-only v1 — no trading, no wallet keys, no credentials required
  • No SSRF — every endpoint is explicitly mapped. No generic pass-through tools
  • Rate limiting — per-endpoint token buckets matching Polymarket's documented limits
  • Credential scrubbing — sensitive values stripped from error output
  • Write gates (v2) — POLYMARKET_WRITE_ENABLED env + per-call confirm=true parameter
  • HTTP transport auth — optional bearer token for remote deployment

Rate Limits

Token-bucket rate limiter per endpoint group:

Group Limit / 10s Endpoints
clob_general 9,000 Health, tick-size
clob_pricing 1,500 Book, price, midpoint, spread
clob_batch 500 Batch books, prices, spreads
clob_history 1,000 Price history
gamma_general 4,000 Tags, sports
gamma_discovery 300 Events, markets, search
data_general 1,000 Open interest, leaderboard, trades

Development

make install-dev   # Install all dependencies
make test          # Run unit tests (99 tests)
make test-cov      # Tests with coverage report
make check         # Lint + format + typecheck

Tech stack

  • Python 3.12+ / FastMCP / httpx / Pydantic
  • uv (package manager) / ruff (lint+format) / mypy (strict types) / pytest

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for piersdd from gravatar.com piersdd

Credits

Author: groupthink-dev

License

MIT

Requires

Python >=3.12

Tags

blade mcp polymarket prediction-market sidereal

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

polymarket_blade_mcp-0.2.0.tar.gz (98.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

polymarket_blade_mcp-0.2.0-py3-none-any.whl (16.1 kB view details)

Uploaded Python 3

File details

Details for the file polymarket_blade_mcp-0.2.0.tar.gz.

File metadata

  • Download URL: polymarket_blade_mcp-0.2.0.tar.gz
  • Upload date:
  • Size: 98.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for polymarket_blade_mcp-0.2.0.tar.gz
Algorithm Hash digest
SHA256 e381fac73e3a0df05ac80d27ba5b55208ef598bd783341799bf80783df6f23cc
MD5 7b9423338512ba55434b6234ea41e637
BLAKE2b-256 475c49c72840425336be7bb1999df46527623bd46892f2e74f474905c6130613

See more details on using hashes here.

Provenance

The following attestation bundles were made for polymarket_blade_mcp-0.2.0.tar.gz:

Publisher: publish.yml on Groupthink-dev/polymarket-blade-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polymarket_blade_mcp-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for polymarket_blade_mcp-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 da480fe340118c4080e6ef43e6aae5782d8faa22693884adc5c18a21c283ca5e
MD5 1cde5474b9a265f448dceceb367ad607
BLAKE2b-256 ecb6b2ad50862aeca27c4be0d52d2337c4ad8778a1a2b59c05638096f99b556c

See more details on using hashes here.

Provenance

The following attestation bundles were made for polymarket_blade_mcp-0.2.0-py3-none-any.whl:

Publisher: publish.yml on Groupthink-dev/polymarket-blade-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page