
mcp-server-polymarket
io.github.tukorama/mcp-server-polymarket
Polymarket predictions and perps: market data, accounts and gated trading. Unofficial.
Documentation
MCP server and LangGraph tools for Polymarket
mcp-server-polymarket is a Model Context Protocol (MCP) server for the
Polymarket APIs, covering both Predictions (Gamma, CLOB, Data API,
Relayer, Bridge, Combos and the WebSocket feeds) and Perps (perpetual futures, HTTP and
WebSocket). The same tools are packaged for LangGraph and LangChain. Reading needs no account.
Trading and transfers exist too, switched off until you turn them on.
[!WARNING] Unofficial, and not affiliated with Polymarket. Orders and transfers move real money and cannot be undone, and an agent can misread a market. Polymarket restricts trading in some countries and regions; check that you are allowed to trade where you are. Start with
dry_runand small limits. This software comes with no warranty (see the license).
Why this exists
Pointing an agent at the Polymarket APIs goes wrong in a few predictable ways, and each one shaped this package.
- There are seven APIs and two hundred endpoints. The tools are curated: one tool answers one
question (
get_quotesreads best bid, ask, midpoint, spread, tick size and minimum size for any number of tokens in one request) and toolsets keep rarely needed areas out of the context. - Responses are huge. A single event can be 28 KB and a search result 80 KB. Tools return trimmed, typed results with outcomes, prices and token ids paired up, and lists are paged.
- Signing is easy to get subtly wrong. Orders, Deposit Wallet batches and Perps operations are signed locally, checked against the official SDK's test vectors, and never with a guessed wallet type.
- An agent should not be able to spend money by accident. Writes are hidden until you enable them, checked against per-order and daily USD limits and a price-sanity band, and confirmed by the user with a description the server writes, not the model, which shows every signed parameter. Withdrawals go only to addresses provably yours or on an allowlist, and a Combo quote is signed only if its amounts match what the user confirmed.
- Networks fail after sending. A write whose outcome is unknown is journaled, an identical
new request is blocked, and
resend_writeresends the exact signed bytes, which Polymarket deduplicates. Nothing that moves money is ever retried automatically.
Quick start
Reading markets, books, prices, positions and Perps data needs nothing but uv and the server.
Claude Code
claude mcp add polymarket -- uvx mcp-server-polymarket
Cursor
Add to .cursor/mcp.json (or ~/.cursor/mcp.json globally):
{
"mcpServers": {
"polymarket": {
"command": "uvx",
"args": ["mcp-server-polymarket"]
}
}
}
Claude Desktop
{
"mcpServers": {
"polymarket": {
"command": "uvx",
"args": ["mcp-server-polymarket"]
}
}
}
VS Code
Add to .vscode/mcp.json:
{
"servers": {
"polymarket": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-polymarket"]
}
}
}
ChatGPT (Developer Mode / Remote MCP)
Start the server over Streamable HTTP with bearer-token protection and tunnel or host it over HTTPS before pasting the endpoint URL into ChatGPT's Developer Mode connector settings:
POLYMARKET_HTTP_BEARER_TOKEN=change-me uvx mcp-server-polymarket serve --transport streamable-http --host 0.0.0.0 --port 8000
Now ask for something like "What does Polymarket give for a Fed cut in December, and how deep is the book?" or "Show me BTC perp funding over the last week."
Trading
Trading needs the signing extra, your wallet's address and a signing key.
-
Install with signing. Use
uvx --from "mcp-server-polymarket[signing]" mcp-server-polymarketwherever the examples sayuvx mcp-server-polymarket. -
Configure the key and wallet. Put the private key in a file readable only by you and set
POLYMARKET_PRIVATE_KEY_FILEto its path, andPOLYMARKET_WALLET_ADDRESSto your Polymarket wallet (the address shown on polymarket.com, not the key's own address). The server works out the wallet type from the two and refuses a mismatch. -
Create CLOB credentials once, in a terminal:
uvx --from "mcp-server-polymarket[signing]" mcp-server-polymarket authThey are saved to
~/.config/mcp-server-polymarket/session.json, readable only by you. The private key is never written to disk by this package. -
Turn trading on in the server's environment:
POLYMARKET_ALLOW_TRADING=true. Optionally lowerPOLYMARKET_MAX_ORDER_USD(100 by default) andPOLYMARKET_MAX_DAILY_USD(1000). -
Check with
mcp-server-polymarket status, which lists what is configured and every hidden tool with the step that would show it.
{
"mcpServers": {
"polymarket": {
"command": "uvx",
"args": ["--from", "mcp-server-polymarket[signing]", "mcp-server-polymarket"],
"env": {
"POLYMARKET_PRIVATE_KEY_FILE": "/Users/me/.config/polymarket/key",
"POLYMARKET_WALLET_ADDRESS": "0x...",
"POLYMARKET_ALLOW_TRADING": "true",
"POLYMARKET_MAX_ORDER_USD": "20"
}
}
}
}
Your MCP client must support elicitation (asking the user a question mid-call), because every order is confirmed there. A client without it gets a refusal, not a silent order.
Use a session key for day-to-day trading. On a Deposit Wallet, the owner key can do anything, including withdrawing. A session key can trade but cannot move funds out. Authorise one with the owner key, then run the server with the session key instead:
mcp-server-polymarket auth --session-key 0xSESSION_KEY_ADDRESS
and set POLYMARKET_PRIVATE_KEY_FILE to the session key and POLYMARKET_SIGNER_ROLE=session_key.
The wallet and transfer tools need the owner key and stay hidden.
On-chain actions (setup_trading_approvals, split_position, merge_positions,
redeem_positions, deposit_to_perps) go through Polymarket's gasless Relayer and need a Relayer
API key from your Polymarket account: POLYMARKET_RELAYER_API_KEY and
POLYMARKET_RELAYER_API_KEY_ADDRESS.
Perps need a separate session, created once:
mcp-server-polymarket auth --perps # a trading key that cannot withdraw
mcp-server-polymarket auth --perps --read-only
Moving funds (Perps deposits and withdrawals, bridge withdrawals) needs
POLYMARKET_ALLOW_TRANSFERS=true as well, is capped by POLYMARKET_MAX_TRANSFER_USD, and is
always confirmed, whatever POLYMARKET_CONFIRM says.
A safe first run: preview an order with dry_run, place a post-only order at the minimum size
far from the market and cancel it, and on Perps set the leverage you already have.
mcp-server-polymarket logout forgets stored credentials; logout --revoke also deletes the CLOB
API key on Polymarket, logout --builder-key revokes the builder key, and logout --perps
revokes and forgets the Perps session.
LangGraph and LangChain
The langgraph extra gives you plain LangChain tools in the same process, with no MCP server to
run. It also has a prebuilt agent.
uv add "mcp-server-polymarket[langgraph,signing]"
from mcp_server_polymarket.integrations.langgraph import (
create_polymarket_agent,
get_polymarket_tools,
)
agent = create_polymarket_agent("anthropic:claude-sonnet-5-5")
config = {"configurable": {"thread_id": "1"}}
result = await agent.ainvoke({"messages": [("user", "How likely is a Fed cut?")]}, config=config)
# Or take the tools and build your own graph:
tools = get_polymarket_tools(toolsets="auto,+sports", prefix="pm_")
The tools work from sync and async graphs. When trading is enabled, every order or transfer pauses
the graph with interrupt(), carrying the same confirmation text the MCP server would show.
Resume with Command(resume=True) to go ahead; any other value declines. Interrupts need a
checkpointer, which the prebuilt agent creates in memory (pass your own, or checkpointer=None on
LangGraph Platform). get_polymarket_tools() leaves those tools out unless you pass
include_gated=True, because they only work inside a graph with a checkpointer. See
examples/langgraph_agent.py
and the LangGraph Platform app in
examples/langgraph_app.
To keep Polymarket in a separate process, connect over MCP instead. This route needs
langchain[mcp], which LangChain still marks as beta.
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
config = {"mcpServers": {"polymarket": {"command": "uvx", "args": ["mcp-server-polymarket"]}}}
async with MCPAdapter(config) as adapter:
agent = create_agent("anthropic:claude-sonnet-5-5", await adapter.list_tools())
draw_mermaid(agent) draws a graph with its Polymarket tools grouped by toolset and colored by
what they can change. The prebuilt agent without credentials:
---
config:
flowchart:
nodeSpacing: 24
rankSpacing: 12
padding: 8
---
flowchart TB
subgraph agent["Agent graph"]
direction LR
n0([start])
n1["model"]
n2["tools"]
n3([end])
n0 --> n1
n1 -.-> n3
n1 -.-> n2
n2 -.-> n1
end
subgraph tools["Tools"]
direction TB
subgraph tools_row0[" "]
direction LR
subgraph tools_analytics["analytics"]
direction LR
tools_analytics_read["list_positions<br/>list_combo_positions<br/>get_user_overview<br/>get_user_pnl<br/>list_trades<br/>list_activity<br/>list_combo_activity<br/>list_market_holders<br/>get_open_interest<br/>get_event_live_volume<br/>get_resolutions<br/>lookup_tokens<br/>get_leaderboard<br/>list_biggest_wins<br/>get_wallet_approvals"]:::read
end
subgraph tools_perps_market["perps-market"]
direction LR
tools_perps_market_read["get_perps_exchange_info<br/>list_perps_instruments<br/>get_perps_tickers<br/>get_perps_book<br/>get_perps_candles<br/>get_perps_index<br/>list_perps_trades<br/>get_perps_funding_history<br/>get_perps_exchange_stats<br/>get_perps_public_account<br/>list_perps_public_fills<br/>check_perps_invite_code"]:::read
end
subgraph tools_discovery["discovery"]
direction LR
tools_discovery_read["search<br/>list_events<br/>get_event<br/>list_markets<br/>get_market<br/>list_tags<br/>get_tag<br/>list_series<br/>get_series<br/>list_comments<br/>get_profile<br/>list_event_creators"]:::read
end
tools_analytics ~~~ tools_perps_market ~~~ tools_discovery
end
subgraph tools_row1[" "]
direction LR
subgraph tools_docs["docs"]
direction LR
tools_docs_read["search_docs<br/>read_doc"]:::read
end
subgraph tools_market_data["market-data"]
direction LR
tools_market_data_read["get_order_books<br/>get_quotes<br/>get_price_history<br/>get_market_trading_info<br/>list_order_book_markets<br/>get_live_activity"]:::read
end
subgraph tools_system["system"]
direction LR
tools_system_read["get_service_status<br/>auth_status"]:::read
end
tools_docs ~~~ tools_market_data ~~~ tools_system
end
tools_row0 ~~~ tools_row1
end
agent -- tool calls --> tools
subgraph legend["Legend"]
direction TB
legend_read["read-only"]:::read
end
polymarket["Polymarket APIs"]:::external
tools -- HTTPS / WebSocket --> polymarket
tools ~~~ legend
classDef default fill:#64748b,fill-opacity:0.06,stroke:#64748b
classDef read fill:#64748b,fill-opacity:0.14,stroke:#64748b
classDef write fill:#d97706,fill-opacity:0.16,stroke:#d97706
classDef funds fill:#dc2626,fill-opacity:0.16,stroke:#dc2626,stroke-width:2px
classDef external fill-opacity:0,stroke-dasharray:5 4
classDef box fill:#64748b,fill-opacity:0.05,stroke:#64748b,stroke-opacity:0.45
classDef row fill:none,stroke:none
class agent,tools,tools_analytics,tools_perps_market,tools_discovery,tools_docs,tools_market_data,tools_system,legend box
class tools_row0,tools_row1 row
Tools
There are 128 tools in 18 toolsets. Without credentials the default set exposes 49. Tools that need
credentials or a gate appear only when they are configured; auth_status and
mcp-server-polymarket tools explain the rest.
Choose toolsets with POLYMARKET_TOOLSETS: auto (the default), all, predictions, perps, a
list of names, or adjustments such as auto,+sports,-docs.
Always available with auto
| Toolset | Tools |
|---|---|
discovery | search, list_events, get_event, list_markets, get_market, list_tags, get_tag, list_series, get_series, list_comments, get_profile, list_event_creators |
market-data | get_order_books, get_quotes, get_price_history, get_market_trading_info, list_order_book_markets, get_live_activity |
analytics | list_positions, list_combo_positions, get_user_overview, get_user_pnl, list_trades, list_activity, list_combo_activity, list_market_holders, get_open_interest, get_event_live_volume, get_resolutions, lookup_tokens, get_leaderboard, list_biggest_wins, get_wallet_approvals |
perps-market | get_perps_exchange_info, list_perps_instruments, get_perps_tickers, get_perps_book, get_perps_candles, get_perps_index, list_perps_trades, get_perps_funding_history, get_perps_exchange_stats, get_perps_public_account, list_perps_public_fills, check_perps_invite_code |
system | get_service_status, auth_status |
docs | search_docs, read_doc (docs.polymarket.com only) |
With credentials (auto)
| Toolset | Needs | Tools |
|---|---|---|
account | CLOB credentials | get_my_account_status, list_my_open_orders, get_my_order, list_my_trades, get_my_balance_allowance, list_my_notifications, get_my_wallet_status, get_relayer_transaction, list_relayer_transactions, watch_my_orders |
perps-account | Perps session | get_my_perps_account, get_my_perps_portfolio, list_my_perps_orders, list_my_perps_fills, get_my_perps_history, list_my_perps_funding, list_my_perps_transfers, get_my_perps_rewards, list_my_perps_notifications, watch_my_perps |
trading | signer + ALLOW_TRADING | place_limit_order, place_market_order, place_orders, resend_write, mark_notifications_read; with ALLOW_CANCEL alone: cancel_orders, cancel_all_orders, list_unconfirmed_writes |
wallet | owner key + Relayer key + ALLOW_TRADING | setup_trading_approvals, split_position, merge_positions, redeem_positions |
perps-trading | Perps session + ALLOW_TRADING | place_perps_orders, modify_perps_orders*, set_perps_leverage, adjust_perps_margin, apply_perps_referral_code, create_perps_invite_code, mark_perps_notifications_read; with ALLOW_CANCEL: cancel_perps_orders, cancel_all_perps_orders, set_perps_auto_cancel; with ALLOW_TRANSFERS: deposit_to_perps, withdraw_from_perps, transfer_perps_internal* |
On request (+name)
| Toolset | Tools |
|---|---|
sports | get_sports_metadata, list_teams, list_sports_results, watch_sports |
rewards | list_reward_markets, get_maker_rebates, get_my_reward_earnings, list_my_reward_markets, get_my_order_scoring |
streams | watch_market, watch_live_data, watch_perps_market |
bridge | list_bridge_assets, get_bridge_quote, get_bridge_status, create_deposit_addresses, create_withdrawal_addresses (transfers) |
combos | list_combo_markets, get_combo_request, plan_collateral_return, trade_combo*, execute_collateral_return* (trading) |
builder | get_builder_leaderboard, list_builder_trades, list_builder_api_keys, list_relayer_api_keys, get_my_perps_builder, set_perps_builder_approval (trading) |
perps-extras | get_perps_leaderboard, list_perps_competitions, get_perps_competition, get_perps_position_snapshots, get_my_perps_blp, set_perps_blp_enrollment (trading) |
* Experimental: the wire format comes from the documentation and has not been verified against the live API.
watch_* tools open a WebSocket, collect events for a few seconds or up to a count, and return a
summary; they do not stream indefinitely.
Resources: polymarket://perps/instruments, polymarket://markets/{slug}, and reference pages
under polymarket://docs/ (concepts, trading, perps, safety).
Prompts: research_market, review_portfolio and plan_perps_trade. None of them trades.
API coverage
Every operation in the published OpenAPI and AsyncAPI specifications listed in
docs.polymarket.com/llms.txt, plus the routes the guides
describe, is either called by a tool, used by the CLI (key creation and revocation), or listed
with a reason in
coverage.py.
A test checks this against a manifest generated from the specifications, and that the test suite
calls every endpoint. Deliberately left out: CLOB heartbeats (they need a five-second loop),
Combos market making (a 400 ms quote loop), and Perps PATCH /v1/account/builder, whose signed
payload is undocumented. The separate Polymarket US exchange is not covered.
Configuration
All settings are environment variables with the POLYMARKET_ prefix. A .env file in the
working directory can set only the harmless ones (TOOLSETS, HTTP_TIMEOUT, LOG_LEVEL).
Keys, wallet, credentials, gates, limits, confirmation mode, allowlist, builder settings, service
URLs, file paths and the bearer token have to be set in the real environment (for example the
client's env block), so that a file in a project directory cannot swap the signing key, redirect
funds or turn trading on.
| Variable | Default | Purpose |
|---|---|---|
PRIVATE_KEY_FILE, PRIVATE_KEY | Signing key (owner or session key). Prefer the file | |
WALLET_ADDRESS | Your Polymarket wallet. Needed for anything signed | |
SIGNER_ROLE | owner | session_key when the key is a Deposit Wallet session key |
SIGNATURE_TYPE | detected | 0 EOA, 1 Proxy, 2 Safe, 3 Deposit Wallet; only checked against detection |
API_KEY, API_SECRET, API_PASSPHRASE, ADDRESS | Existing CLOB credentials, for account reads without a private key | |
RELAYER_API_KEY, RELAYER_API_KEY_ADDRESS | Relayer key for wallet transactions | |
PERPS_PROXY, PERPS_SECRET, PERPS_PROXY_KEY | An existing Perps session instead of auth --perps | |
TOOLSETS | auto | See Tools |
ALLOW_CANCEL | false | Cancel tools only |
ALLOW_TRADING | false | Orders, leverage, wallet transactions (includes cancel) |
ALLOW_TRANSFERS | false | Deposits, withdrawals and transfers |
CONFIRM | elicit | none skips the confirmation question for trading, never for transfers |
MAX_ORDER_USD | 100 | Per order. 0 blocks, unlimited lifts |
MAX_DAILY_USD | 1000 | Per UTC day, separately for orders, Perps orders and transfers |
MAX_PERPS_ORDER_USD | 500 | Per Perps order (reduce-only orders are exempt) |
MAX_PERPS_LEVERAGE | 5 | Highest leverage set_perps_leverage accepts |
MAX_TRANSFER_USD | 100 | Per transfer |
MAX_PRICE_DEVIATION | 0.10 | Refuse prices this far through the book: 0.10 pUSD for prediction markets, 10% of the mark for Perps |
TRANSFER_ALLOWLIST | Comma-separated recipients other than your own wallet | |
BUILDER_API_KEY, BUILDER_SECRET, BUILDER_PASSPHRASE, BUILDER_CODE, PERPS_BUILDER | Builder program attribution | |
SESSION_FILE, PERPS_SESSION_FILE, JOURNAL_FILE | ~/.config/mcp-server-polymarket/… | Stored credentials and the write journal |
CACHE_DIR | ~/.cache/mcp-server-polymarket | Instrument, label and docs cache |
HTTP_TIMEOUT | 20 | Seconds per HTTP request |
HTTP_BEARER_TOKEN | Required by the HTTP transport on a non-local address | |
LOG_LEVEL | INFO | Logs go to stderr |
GAMMA_URL, CLOB_URL, DATA_URL, PERPS_URL, … | Polymarket's | Service endpoints, https and wss only |
On Windows the two directories are %APPDATA%\mcp-server-polymarket and
%LOCALAPPDATA%\mcp-server-polymarket, and files are protected by your user profile rather than
POSIX permissions.
To serve over HTTP:
POLYMARKET_HTTP_BEARER_TOKEN=change-me mcp-server-polymarket serve --transport streamable-http --host 0.0.0.0
The server refuses a non-local address without a token. /health stays open for probes. Do not
expose a server with trading enabled to anyone you would not hand your wallet.
How it behaves
Confirmation. Each order, wallet transaction and transfer is described by the server from
market data (outcome name, price, shares, cost, wallet, recipient) and confirmed by the user before
it is signed. Declining returns declined; nothing is sent. Cancels are not confirmed.
Checks before signing. Tick size (off-tick prices are refused, never rounded), minimum size, distance from the best price or mark, per-order and daily limits, leverage cap, Protocol V1/V2 exchange version, and Polymarket's geoblock check, which fails closed. Missing balance or allowance is reported, never fixed by an automatic approval.
Unknown outcomes. If the connection drops after a write is sent, the tool returns
unknown with a request_id. An identical request is blocked until you check
(list_unconfirmed_writes) and either resend the same bytes (resend_write) or let it expire
after 15 minutes. The journal keeps signed bodies only for those writes.
Retries. Reads retry with backoff and honour Retry-After. Orders, cancels and transfers are
never retried automatically.
Long calls. Claude Desktop has been reported to cancel stdio tool calls after about a minute,
so for that client waits (Relayer confirmations, watch_*) are capped at 45 seconds. A Relayer
transaction still unconfirmed then returns pending with an id for get_relayer_transaction.
What is never logged. Private keys, API secrets, passphrases, HMAC signatures and signed bodies are masked in logs and errors by exact value. Market descriptions and comments are stripped of control and bidirectional characters, and the agent guide marks them as untrusted.
Limitations
- Read tools have been run against the live APIs. Order placement, cancels, wallet transactions, Perps operations and transfers have been tested against recorded responses, the official SDK's signing test vectors and a differential test against the SDK, but not with real funds. The tools marked experimental are less proven still. Make your first live writes small.
- Polymarket changes its APIs often.
live.ymlruns the live read tests, the manifest check and the SDK comparison weekly. Protocol V2 markets start on 2026-11-23; the V2 exchange contracts and position ids are supported but could not be tried before launch. - Wallet transactions support Deposit Wallets only. Proxy and Safe wallets can trade on the CLOB
but cannot use the
wallettoolset, because their Relayer signing is not documented. An EOA (signature type 0) cannot use the gasless Relayer at all. - Session keys cannot trade Combos.
session.jsonandperps_session.jsonare plaintext protected by file permissions. Keep the private key in a file of its own, or in your own secret store passed through the environment.- Check that your use of automated trading complies with Polymarket's terms and the law where you are.
Development
To point a client at a checkout, use
uvx --from "/path/to/mcp-server-polymarket[signing]" mcp-server-polymarket, or
uv add --editable ../mcp-server-polymarket from your LangGraph project. Start with the guided
codebase tour in
onboarding/, and see
CONTRIBUTING.md
for contributor workflows.
The protocol details follow Polymarket's documentation and the MIT-licensed polymarket-client SDK, which is used as a test oracle; see NOTICE.
License
mcp-server-polymarketpip install mcp-server-polymarket