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.

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. Withdrawals go only to your own wallet or an allowlist.

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

Related MCP server: Polymarket MCP Server

Quick start

Reading markets, books, prices, positions and Perps data needs nothing but the server.

Claude Code

claude mcp add polymarket -- uvx mcp-server-polymarket

Claude Desktop, Cursor, VS Code and others

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

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

With credentials (auto)

On request (+name)

* 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 also works, except for the gates, limits, confirmation mode, allowlist, builder settings, service URLs, file paths and the bearer token, which have to be set in the real environment so that a file in a project directory cannot turn trading on.

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. See CONTRIBUTING.md and RELEASING.md.

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