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 US MCP server search for Fed rate cut markets and show the best bid/ask"
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 server for the Polymarket US retail REST API, supporting streamable HTTP and stdio. It exposes 58 tools for market and event discovery, prices and order books, sports, tags, account and portfolio, orders, combos, RFQs, and incentives. Tool input schemas are derived from the published Polymarket OpenAPI schemas; use your MCP client's tool listing to see available fields, required inputs, and pagination options.
Trading tools operate on your real account. The MCP endpoint has no authentication: anyone able to connect can read account information and submit or cancel trades. It binds to localhost by default. Only change HOST if the endpoint is protected by a trusted network boundary or an authenticated proxy.
Install Python 3.14 and uv. Create a Polymarket US account and API key as described in Polymarket's authentication guide. Identity verification and account funding may be required for trading.
uv sync --locked
cp .env.example .env
# Edit .env and add your Polymarket US key ID and secret key.
uv run python main.pyConnect an MCP client using streamable HTTP at http://127.0.0.1:8000/mcp. Configure that URL in the client's remote MCP server settings. HOST and PORT select the server's bind address and port; both keys are required on startup. The server reads .env from the project directory; existing environment variables take precedence over values in the file. Protect the secret as you would any trading credential; do not commit it to source control.
For local MCP clients that launch a server process, use:
uv run --directory /absolute/path/to/polymarket-us-mcp python main.py --transport stdioFor example, a client using an mcpServers configuration can launch it with:
{
"mcpServers": {
"polymarket-us": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/polymarket-us-mcp", "python", "main.py", "--transport", "stdio"]
}
}
}Replace the example path with your project directory and make sure uv is available to the client. The server reads the same project .env and environment variables in stdio mode. HOST and PORT apply only to HTTP. Stdio runs as a child of the MCP client and does not open a listening port. Both transports expose the same live trading tools.
Related MCP server: Polymarket MCP Server
Start with search, get_events, get_markets, get_market_by_slug, get_market_book, or get_market_bbo. List tools accept a query object containing the exact documented query parameters, including pagination; for example, get_events with {"query": {"limit": 10, "offset": 0}}. Responses come directly from Polymarket.
Use get_account_balances, get_user_positions, and get_open_orders to inspect the account. For a limit order, the following example buys two YES contracts at $0.55 each, subject to the market's rules. Replace the slug and values with the intended trade. Prices are USD strings, and quantity is in contracts.
Call preview_order first:
{
"body": {
"request": {
"marketSlug": "your-market-slug",
"intent": "ORDER_INTENT_BUY_LONG",
"type": "ORDER_TYPE_LIMIT",
"price": {"value": "0.55", "currency": "USD"},
"quantity": 2,
"tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL"
}
}
}After reviewing the preview, create_order takes the same order directly under body, without the request wrapper. A call to create_order submits a live order. The full orders documentation describes intents, order types, time in force, and other options. The server also provides order lookup, modification, cancellation, closing positions, and batch operations. A returned batch cancellation or modification ID does not itself confirm the exchange applied the operation.
Trading and other mutations are never automatically retried. If a mutation times out, loses its connection, or receives an ambiguous server error, the result is outcome_unknown: inspect orders, positions, or the relevant RFQ before retrying. API errors include a status and request ID when available; raw error bodies are not returned to avoid reflecting sensitive data.
The server uses the official Python SDK for supported operations and signed SDK requests for documented endpoints that do not have resource methods. The catalog is a snapshot of the public Polymarket US retail OpenAPI schemas and the documented retail combos endpoint; update it when the upstream API changes. WebSocket streaming and institutional APIs are outside this server's scope.
uv run python -m unittest discover -s tests -vTests use a mocked Polymarket transport, including an actual local HTTP MCP connection; they do not place trades. For optional live read-only verification, start the server with your keys and call get_markets or get_account_balances from an MCP client. Do not use a live trading tool to verify setup unless you intend to submit a real trade.
The GitHub Actions workflow builds the image for Linux amd64 and arm64 and publishes it as ghcr.io/chand1012/polymarket-us-mcp. Pushes to main or master publish latest; version tags beginning with v publish a matching image tag, and published builds also receive a commit SHA tag. Pull requests build and test without publishing.
Build and run locally, supplying credentials at runtime:
docker build -t polymarket-us-mcp .
docker run --rm --env-file .env -e HOST=0.0.0.0 -e PORT=8000 \
-p 127.0.0.1:8000:8000 polymarket-us-mcpReplace the image name with ghcr.io/chand1012/polymarket-us-mcp:latest to run a published image. The server listens on all interfaces inside the container so Docker can forward requests; the example publishes the port only on the host's loopback interface. To restrict access to a tailnet, replace 127.0.0.1 in the -p mapping with the host's Tailscale IPv4 address and apply your Tailscale access rules. Do not set HOST inside the container to the host's Tailscale IP, which normally does not exist in the container network namespace. Anyone who can connect to the published port can use the account's trading tools.
To run the stdio transport instead, pass --transport stdio after the image name and keep standard input open with -i; no port mapping is needed. Do not allocate a TTY for MCP communication.
LIVE ACCOUNT ACTION: Accepts one side of a quote. This operation may affect real funds or account state.
Inputs: body (required), rfqId (required), quoteId (required).
LIVE ACCOUNT ACTION: Cancel all open orders, optionally filtered by market slugs This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Cancel up to 20 orders in a single request. If any entry fails request-shape validation, the whole batch is rejected by the gateway before reaching the exchange. The exchange may silently ignore unknown orderIds. canceledOrderIds is an echo of the request, not a confirmation; observe actual outcomes on the order stream. This operation may affect real funds or account state. Returned IDs may not confirm exchange execution; verify the outcome.
Inputs: body (required).
LIVE ACCOUNT ACTION: Cancel a specific order by its exchange-assigned ID This operation may affect real funds or account state.
Inputs: body (required), orderId (required).
LIVE ACCOUNT ACTION: Create an order to close an existing position in a market. This will sell all contracts held in the specified market. This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Confirms an accepted quote during last look. This operation may affect real funds or account state.
Inputs: body (required), rfqId (required), quoteId (required).
LIVE ACCOUNT ACTION: Creates or returns the combo instrument for the supplied legs. Each authenticated exchange participant may create up to 1,000 new combo instruments per week across all of its accounts. The quota resets Monday at 00:00 UTC. Returning an existing canonical combo does not consume the quota. This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Create up to 20 orders in a single request. If any entry fails request-shape validation, the whole batch is rejected by the gateway before reaching the exchange. Per-entry exchange outcomes (accept, fill, reject) are delivered on the order stream, not in this response. createdOrderIds are returned in request order. This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Create a new order to enter into a market This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Creates a quote using the authenticated Retail account. Every successful call returns a new quoteId, including replacements. See quote replacement. This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Creates a combo RFQ using the authenticated Retail account. This operation may affect real funds or account state.
Inputs: body (required).
LIVE ACCOUNT ACTION: Deletes a quote so it can no longer be accepted. This operation may affect real funds or account state.
Inputs: rfqId (required), quoteId (required).
LIVE ACCOUNT ACTION: Closes an open RFQ. This operation may affect real funds or account state.
Inputs: rfqId (required).
Returns a dense, ascending OHLC candle series per requested asset between from and to, one candle per bucket. Buckets with no ticks are gap-filled: close is carried forward, open/high/low equal that close, and tick_count is 0. The server clamps rather than rejects: a to of 0 or in the future becomes now, and from is raised so the series holds at most 3600 candles. That count is the only size limit, so the widest window scales with the bucket: an hour at 1S, 60 hours at 1M, 150 days at 1H. The effective bounds are echoed on each series. Duplicate assets are deduped; the response holds one series per distinct asset. Match a series to a requested asset by its asset field, never by position: the order is not guaranteed, and the REST surface returns the series sorted by symbol because a repeated query parameter does not keep its order. An unknown symbol, or an asset whose markets are not available yet, fails the whole request with 404 (asset price history is not available). An available asset with no prices yet returns an empty series; an unknown class is rejected.
Inputs: query.
Get user's current account balances including buying power, asset values, and pending transactions
Inputs: no named parameters.
Get activities for a user including trades, position resolutions, and account balance changes
Inputs: query.
Retrieve leagues with pagination (max 50 per page)
Inputs: query.
Retrieve all sports
Inputs: no named parameters.
Returns the combo matching the exact symbol.
Inputs: query (required).
Retrieve a specific event by its ID
Inputs: id (required), query.
Resolve a partner external event ID (e.g. OpticOdds fixture ID) to the internal event and its mapped market sides
Inputs: externalId (required), partnerKey (required).
Retrieve an event by its slug
Inputs: slug (required), query.
Retrieve all events
Inputs: query.
Retrieve events for a league by its slug (e.g., 'nfl', 'nba'). Resolves the league to its active series and returns events.
Inputs: slug (required), query.
Retrieve events for a sport by its slug (e.g., 'football', 'basketball'). Fetches all leagues for the sport, collects their active series, and returns combined events.
Inputs: slug (required), query.
Get events filtered by tag slug, sorted by volume descending by default
Inputs: slug (required), query.
Returns active and historical incentive programs grouped by market.
Inputs: query.
Retrieve a league by its slug
Inputs: slug (required).
Retrieve current market data (best bid/offer, stats) for a specific market by its slug in a lightweight format
Inputs: slug (required).
Retrieve current market data (order book, stats) for a specific market by its slug
Inputs: slug (required).
Retrieve a specific market by its ID
Inputs: id (required).
Retrieve a specific market by its slug
Inputs: slug (required).
Retrieve all markets
Inputs: query.
Retrieve the settlement price for a specific market by its slug
Inputs: slug (required).
Get all open orders for the authenticated user
Inputs: query.
Get details for a specific order by its exchange-assigned ID
Inputs: orderId (required).
Returns book-derived Yes and No display prices for one market. Use the market slug as symbol.
Supported fixed profiles:
INTERVAL_1H with fidelity=1: approximately one-minute points for the last hour
INTERVAL_6H with fidelity=1: approximately one-minute points for the last six hours
INTERVAL_1D with fidelity=5: five-minute points for the last day
INTERVAL_1W with fidelity=180: three-hour points for the last week
INTERVAL_1M with fidelity=180: three-hour points for the last 30 days
INTERVAL_ALL with fidelity=180: three-hour points for newer markets and daily points for longer histories
INTERVAL_LIVE with fidelity=1: from 15 minutes before the event starts through now
For a custom range, provide both Unix timestamps and use fidelity=1. Custom ranges are intended for short windows of up to 24 hours and return stored observations, which may be irregular or more frequent than once per minute.
longPrice is the Yes display price, normally derived from the best ask. shortPrice is the No display price, normally derived from one minus the best bid. They can sum to more than 1 because they preserve the bid-ask spread; these are not individual trades.
The endpoint supports one market per request. Cache identical responses for at least 30 seconds, stagger refreshes across markets, and observe the 20 requests/second/IP public limit. For live updates after loading history, use the Markets WebSocket.
Inputs: query (required).
Returns quotes matching the query filters.
Inputs: query.
Returns RFQs matching the query filters.
Inputs: query.
Returns anonymous original fills where either order originated from an RFQ, newest first. Includes single instruments, combos, and later fills on resting orders. Repeat the same filters and limit with each cursor; an empty cursor ends the traversal. History is eventually visible. Requery overlapping time windows to find late arrivals and deduplicate by tradeId. Later corrections and busts do not amend these prints.
Inputs: query.
Returns the public RFQ user ID for the authenticated participant.
Inputs: no named parameters.
Retrieve all series
Inputs: query.
Retrieve a specific series by its ID
Inputs: id (required).
Retrieve a sport by its slug, with all leagues attached
Inputs: slug (required).
Fetch sports data
Inputs: no named parameters.
Retrieve events sections for a sport series (optional trending, optional live, and sport section). Same structure as home page.
Inputs: seriesId (required), query.
Fetch sports players, filterable by abbreviation, name, id, team, or provider reference
Inputs: query.
Fetch sports teams data for enriching sports events
Inputs: query.
Fetch sports teams data for a specific provider
Inputs: query.
Get a tag by its ID
Inputs: id (required).
Get a tag by its slug
Inputs: slug (required).
Get ranked tags with optional filtering
Inputs: query.
Get user's trading positions across all markets or filtered by specific market
Inputs: query.
Returns rewards earned by the authenticated caller. Each entry sums all payouts for a single (market, date) pair, where date is in Eastern Time.
Inputs: query.
LIVE ACCOUNT ACTION: Modify up to 20 existing orders in a single request. Each entry is forwarded to the exchange as a cancel-replace. If any entry fails request-shape validation, the whole batch is rejected by the gateway before reaching the exchange. The exchange may silently ignore unknown orderIds. modifiedOrderIds is an echo of the request, not a confirmation; observe actual outcomes on the order stream. This operation may affect real funds or account state. Returned IDs may not confirm exchange execution; verify the outcome.
Inputs: body (required).
LIVE ACCOUNT ACTION: Modify an existing order in the marketplace. Allows changing price, quantity, time in force, and other parameters. This operation may affect real funds or account state.
Inputs: body (required), orderId (required).
Preview an order before submission to validate parameters and see expected fills
Inputs: body (required).
Search for a given query
Inputs: query.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 58 tools
The set contains many overlapping read tools: get_sports vs get_all_sports, get_events vs get_events_by_sport_slug/get_events_by_league_slug/get_events_for_a_tag, and get_price_history vs the bucketed OHLC tool. Descriptions add parameters, but an agent still faces multiple near-duplicate retrieval paths and must infer which variant to use.
Most names use snake_case with a clear verb (get_, create_, cancel_, modify_, delete_), which is predictable. There are minor deviations such as the extremely long get_a_bucketed_ohlc... name and inconsistent 'all' qualifiers (get_sports vs get_all_sports), but not mixed casing/styles.
58 tools is an extreme overload for an MCP surface; the calibration explicitly treats 50+ tools as a mismatch. Many retrieval variants and batch/lifecycle operations could be consolidated or exposed via parameters.
The surface covers the domain broadly: events/markets/series/sports/tags, price history/OHLC, order lifecycle (create/preview/modify/cancel/batch), RFQs/quotes/combos, and account/positions/activities/balances/incentives. Minor gaps remain around some alternate lookup keys and post-trade/order-history specifics, but core workflows are represented.
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Hosted MCP for Kalshi prediction markets: search, odds, order books, settlement rules, and trading.
Polymarket MCP — prediction-market data via Gamma + CLOB + Data public APIs.
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
