Repository avatar
Monitoring
v0.1.0
active

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

PyPI CI License: MIT

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_run and 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_quotes reads 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_write resends 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.

  1. Install with signing. Use uvx --from "mcp-server-polymarket[signing]" mcp-server-polymarket wherever the examples say uvx mcp-server-polymarket.

  2. Configure the key and wallet. Put the private key in a file readable only by you and set POLYMARKET_PRIVATE_KEY_FILE to its path, and POLYMARKET_WALLET_ADDRESS to 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.

  3. Create CLOB credentials once, in a terminal:

    uvx --from "mcp-server-polymarket[signing]" mcp-server-polymarket auth
    

    They are saved to ~/.config/mcp-server-polymarket/session.json, readable only by you. The private key is never written to disk by this package.

  4. Turn trading on in the server's environment: POLYMARKET_ALLOW_TRADING=true. Optionally lower POLYMARKET_MAX_ORDER_USD (100 by default) and POLYMARKET_MAX_DAILY_USD (1000).

  5. 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

ToolsetTools
discoverysearch, list_events, get_event, list_markets, get_market, list_tags, get_tag, list_series, get_series, list_comments, get_profile, list_event_creators
market-dataget_order_books, get_quotes, get_price_history, get_market_trading_info, list_order_book_markets, get_live_activity
analyticslist_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-marketget_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
systemget_service_status, auth_status
docssearch_docs, read_doc (docs.polymarket.com only)

With credentials (auto)

ToolsetNeedsTools
accountCLOB credentialsget_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-accountPerps sessionget_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
tradingsigner + ALLOW_TRADINGplace_limit_order, place_market_order, place_orders, resend_write, mark_notifications_read; with ALLOW_CANCEL alone: cancel_orders, cancel_all_orders, list_unconfirmed_writes
walletowner key + Relayer key + ALLOW_TRADINGsetup_trading_approvals, split_position, merge_positions, redeem_positions
perps-tradingPerps session + ALLOW_TRADINGplace_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)

ToolsetTools
sportsget_sports_metadata, list_teams, list_sports_results, watch_sports
rewardslist_reward_markets, get_maker_rebates, get_my_reward_earnings, list_my_reward_markets, get_my_order_scoring
streamswatch_market, watch_live_data, watch_perps_market
bridgelist_bridge_assets, get_bridge_quote, get_bridge_status, create_deposit_addresses, create_withdrawal_addresses (transfers)
comboslist_combo_markets, get_combo_request, plan_collateral_return, trade_combo*, execute_collateral_return* (trading)
builderget_builder_leaderboard, list_builder_trades, list_builder_api_keys, list_relayer_api_keys, get_my_perps_builder, set_perps_builder_approval (trading)
perps-extrasget_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.

VariableDefaultPurpose
PRIVATE_KEY_FILE, PRIVATE_KEYSigning key (owner or session key). Prefer the file
WALLET_ADDRESSYour Polymarket wallet. Needed for anything signed
SIGNER_ROLEownersession_key when the key is a Deposit Wallet session key
SIGNATURE_TYPEdetected0 EOA, 1 Proxy, 2 Safe, 3 Deposit Wallet; only checked against detection
API_KEY, API_SECRET, API_PASSPHRASE, ADDRESSExisting CLOB credentials, for account reads without a private key
RELAYER_API_KEY, RELAYER_API_KEY_ADDRESSRelayer key for wallet transactions
PERPS_PROXY, PERPS_SECRET, PERPS_PROXY_KEYAn existing Perps session instead of auth --perps
TOOLSETSautoSee Tools
ALLOW_CANCELfalseCancel tools only
ALLOW_TRADINGfalseOrders, leverage, wallet transactions (includes cancel)
ALLOW_TRANSFERSfalseDeposits, withdrawals and transfers
CONFIRMelicitnone skips the confirmation question for trading, never for transfers
MAX_ORDER_USD100Per order. 0 blocks, unlimited lifts
MAX_DAILY_USD1000Per UTC day, separately for orders, Perps orders and transfers
MAX_PERPS_ORDER_USD500Per Perps order (reduce-only orders are exempt)
MAX_PERPS_LEVERAGE5Highest leverage set_perps_leverage accepts
MAX_TRANSFER_USD100Per transfer
MAX_PRICE_DEVIATION0.10Refuse prices this far through the book: 0.10 pUSD for prediction markets, 10% of the mark for Perps
TRANSFER_ALLOWLISTComma-separated recipients other than your own wallet
BUILDER_API_KEY, BUILDER_SECRET, BUILDER_PASSPHRASE, BUILDER_CODE, PERPS_BUILDERBuilder program attribution
SESSION_FILE, PERPS_SESSION_FILE, JOURNAL_FILE~/.config/mcp-server-polymarket/…Stored credentials and the write journal
CACHE_DIR~/.cache/mcp-server-polymarketInstrument, label and docs cache
HTTP_TIMEOUT20Seconds per HTTP request
HTTP_BEARER_TOKENRequired by the HTTP transport on a non-local address
LOG_LEVELINFOLogs go to stderr
GAMMA_URL, CLOB_URL, DATA_URL, PERPS_URL, …Polymarket'sService 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.yml runs 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 wallet toolset, 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.json and perps_session.json are 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

MIT