Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Polymarket MCP Server search for markets about the next US presidential election"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that exposes read-only tools for querying live Polymarket prediction-market data via the public Gamma API. Built with FastMCP.
No API key required — the Gamma API is public and unauthenticated.
All tools are read-only (readOnlyHint: true).
Tool | Params | Purpose |
|
| Free-text search across event titles, market questions, and descriptions. Primary discovery tool when the user names a topic but not an ID. |
|
| Browse open, unresolved events sorted by a field. Use for "what's hot / most liquid / expiring soon". |
|
| Full detail for one event and all of its nested markets. Use when the user cares about a whole topic (all candidates, all strike brackets). |
|
| Full detail for a single market, including order-book edges ( |
get_active_markets sort keys
| Meaning |
| Cumulative USD traded — "biggest overall" |
| USD currently in the order book — "where you can trade now" |
| Resolution deadline — "expiring soonest" |
| Listing date |
| Closest to 50/50 — "most contested" (best-effort) |
Known tag_slug values: politics, crypto, sports, elections, geopolitics. Omit for all categories.
Fields that require drilling down — search_markets returns less than the list/detail tools, and get_event returns less per-market than get_market:
Field |
|
|
|
|
| ❌ | ✅ | ✅ | ✅ |
| ❌ | ✅ (event-level) | ✅ (event-level) | ✅ |
| ❌ | ❌ | ✅ | ✅ |
| ❌ | ❌ | ❌ | ✅ |
Full market | ❌ | ❌ | ❌ | ✅ |
Related MCP server: Polymarket MCP Server
The server sends these conventions to clients on connect as part of its instructions, but they're worth knowing upfront:
Event vs. market. An event is a topic that groups one or more related markets (e.g. event Democratic Nominee 2028 groups per-candidate markets). A market is a single binary question with a share price in [0, 1] that reflects the crowd-estimated probability.
outcome_prices and outcomes are JSON-encoded strings, not lists. Parse with json.loads, e.g. '["0.0135", "0.9865"]' → ["0.0135", "0.9865"]. For binary markets, index 0 is YES, index 1 is NO, and values sum to ~1.0. outcome_prices is null for untraded markets.
Prices are probabilities, not dollars. best_bid, best_ask, last_trade_price, and the parsed entries of outcome_prices are all in [0, 1].
USD units. volume, volume_24hr, liquidity are USD (float, may be null).
Dates. end_date is ISO 8601 UTC (e.g. "2026-07-01T04:00:00Z") or null when an event's sub-markets have staggered dates.
Package | Version | Purpose |
| MCP server framework | |
| HTTP client for the Polymarket Gamma API |
Requires Python 3.10+.
git clone https://github.com/jiroamato/polymarket_mcp.git
cd polymarket_mcp
uv syncuv sync reads pyproject.toml and installs all dependencies into an isolated virtual environment automatically.
git clone https://github.com/jiroamato/polymarket_mcp.git
cd polymarket_mcp
pip install -e .Installing the package also registers a polymarket-mcp console script (see pyproject.toml) that you can use as the command in any MCP client config.
There are three ways to wire this server into an MCP client, in increasing order of "how much JSON you touch".
FastMCP ships install commands that write the client config for you.
Claude Code:
fastmcp install claude-code src/polymarket_mcp/server.pyClaude Desktop:
fastmcp install claude-desktop src/polymarket_mcp/server.py --server-name "Polymarket"Useful flags: --python 3.11, --project /path/to/polymarket_mcp, --with httpx, --env KEY=VALUE, --env-file .env. See fastmcp install --help for the full list.
If you've already installed dependencies into a Python environment (via uv sync or pip install -e .), point the client directly at that interpreter.
Claude Code — add to your .claude.json:
{
"mcpServers": {
"polymarket": {
"command": "/path/to/python",
"args": [
"/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}Claude Desktop — add to claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"polymarket": {
"command": "/path/to/python",
"args": [
"/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}Replace /path/to/python with the full path to your interpreter (e.g., C:/Users/you/miniforge3/python.exe, /Users/you/.venv/bin/python).
If you ran pip install -e ., you can instead use the installed console script:
{
"mcpServers": {
"polymarket": {
"command": "/path/to/polymarket-mcp"
}
}
}Standalone:
python src/polymarket_mcp/server.py
# or, after `pip install -e .`:
polymarket-mcpuv run (no pre-installed deps)uv handles dependency isolation automatically — no need to install fastmcp or httpx yourself.
Claude Code:
claude mcp add polymarket -- uv run --with fastmcp --with httpx fastmcp run src/polymarket_mcp/server.pyOr add to your .claude.json:
{
"mcpServers": {
"polymarket": {
"command": "uv",
"args": [
"run",
"--with", "fastmcp",
"--with", "httpx",
"fastmcp",
"run",
"/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
]
}
}
}Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"polymarket": {
"command": "uv",
"args": [
"run",
"--with", "fastmcp",
"--with", "httpx",
"fastmcp",
"run",
"/absolute/path/to/polymarket_mcp/src/polymarket_mcp/server.py"
]
}
}
}Standalone:
uv run fastmcp run src/polymarket_mcp/server.pyOnce connected, try asking your AI assistant:
"What are the top prediction markets on Polymarket right now?"
"Search Polymarket for markets about AI."
"Show me the most liquid crypto prediction markets."
"Which politics markets on Polymarket are expiring soonest?"
"Get details on Polymarket event 903 and summarize the candidates."
"For Polymarket market 573655, what's the current spread and 1-day price change?"
# Install dependencies
uv sync
# Run the server locally
uv run fastmcp run src/polymarket_mcp/server.py
# Inspect tools interactively with the MCP Inspector (browser UI)
uv run fastmcp dev inspector src/polymarket_mcp/server.pyThe server itself lives in a single file: src/polymarket_mcp/server.py. Each tool is a plain function decorated with @mcp.tool(annotations={"readOnlyHint": True}); FastMCP generates the JSON schema from the type hints and docstring automatically.
Browse active (open, unresolved) events sorted by a field.
Use this for discovery when the user asks "what's hot / most liquid /
expiring soon" without naming a topic. For keyword search, use
search_markets.
limit: Events to return (default 10, max ~100).
offset: Pagination offset (default 0). Page by incrementing offset
by limit.
order: Sort field. Supported values:
"volume" — cumulative USD traded (default; "biggest overall")
"liquidity" — USD in the order book now ("where you can trade")
"end_date" — resolution deadline ("expiring soonest")
"start_date" — listing date
"competitive" — closest to 50/50 ("most contested"; best-effort semantics)
ascending: False (default) returns largest/latest first.
tag_slug: Category filter. Known slugs include "politics", "crypto", "sports", "elections", "geopolitics". Omit for all categories.
volume_min: Minimum cumulative USD volume. Useful to exclude long-tail markets with near-zero activity.
Returns a list of event dicts with nested markets. Each event has id,
end_date, volume, volume_24hr, liquidity, and markets[]. Each
nested market has id, outcomes, outcome_prices, best_bid,
best_ask, last_trade_price.
Does NOT include event-level active / closed / category, or
market-level closed / liquidity / one_day_price_change. Call
get_market for those.
Inputs: limit, order, offset, tag_slug, +2 more. Returns: result
Get one event with all of its nested markets.
Use when the user cares about a whole topic (all candidates, all strike
brackets, etc.). For one specific sub-question, use get_market.
event_id: Numeric string ID (e.g. "36173"). Obtain from
search_markets or get_active_markets (returned as id).
Returns the event dict with its full markets[]. Notable fields:
volume, volume_24hr, liquidity: USD floats (may be null).
active, closed: state flags; closed = all sub-markets resolved.
end_date: ISO 8601 UTC; null when sub-markets have staggered dates.
markets[].outcome_prices: JSON-encoded probability list; null if
untraded.
markets[].best_bid, best_ask, last_trade_price: probabilities in
[0, 1].
markets[].one_day_price_change: 24h absolute change in probability
(float).
markets[].closed: true once that individual market has resolved.
Does NOT include per-market spread, one_week_price_change, or full
market description / slug. Use get_market for those.
Inputs: event_id (required). Returns: object
Get full details for one market, including order-book edges and momentum.
Use when the user cares about a single specific question (one candidate's
odds, one strike price). For the whole topic, use get_event.
market_id: Numeric string ID (e.g. "573655"). Obtain from
search_markets, get_event, or get_active_markets (returned as id
or markets[].id).
Returns a single market dict. Notable fields:
question: the prediction question itself.
description: full resolution rules (can be long — tells you how the
market settles).
outcome_prices, outcomes: JSON-encoded string lists (see server
instructions).
best_bid, best_ask: order-book edges as probabilities in [0, 1].
spread: best_ask - best_bid (narrower = more liquid).
last_trade_price: most recent fill price (probability).
one_day_price_change, one_week_price_change: absolute change in
probability.
volume, volume_24hr, liquidity: USD floats.
end_date: ISO 8601 UTC resolution deadline.
active, closed: tradeability + resolution state.
Inputs: market_id (required). Returns: object
Search events and markets by free-text keyword.
Use this as the primary discovery tool when the user names a topic but not an event/market ID. Matches against event titles, market questions, and descriptions.
query: Free-text query. Short topical terms work best ("bitcoin", "ukraine", "nba mvp"). Not fuzzy — overly-specific queries may return nothing.
limit: Max results per result type (default 10, typical useful 5-20).
Returns a list of event dicts with nested markets. Key fields:
id: event ID for get_event.
markets[].id: market ID for get_market.
markets[].outcome_prices: JSON-encoded probability list (see server
instructions); can be null for untraded markets.
Does NOT include best_bid / best_ask / last_trade_price /
volume_24hr / spread. Call get_event or get_market on a result
id for order-book data.
Inputs: query (required), limit. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool targets a distinct purpose: browsing active markets, retrieving a full event, getting detailed market info, and searching by keyword. No functional overlap exists.
All tool names follow a consistent verb_noun snake_case pattern: get_active_markets, get_event, get_market, search_markets. The verbs are fitting and predictable.
With 4 tools, the scope is appropriately focused on data retrieval for prediction markets. It's slightly lean but covers the core use cases without being overwhelming.
The tool set covers essential discovery and detail retrieval for events and markets. Minor gaps exist (e.g., no history or category listing), but the core workflow is well-supported.
Read-only Polymarket search, market details, order books, price history, and market cards.
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
Read-only prediction-market data across Kalshi, Polymarket, Limitless: venues, fees, lookups, stats.
Polymarket MCP — prediction-market data via Gamma + CLOB + Data public APIs.