mcp-server-polymarket 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. mcp_server_polymarket-0.1.0/LICENSE +21 -0
  2. mcp_server_polymarket-0.1.0/NOTICE +28 -0
  3. mcp_server_polymarket-0.1.0/PKG-INFO +528 -0
  4. mcp_server_polymarket-0.1.0/README.md +487 -0
  5. mcp_server_polymarket-0.1.0/pyproject.toml +164 -0
  6. mcp_server_polymarket-0.1.0/pyproject.toml.orig +138 -0
  7. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/__init__.py +8 -0
  8. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/__main__.py +3 -0
  9. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/auth_flow.py +289 -0
  10. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/capabilities.py +171 -0
  11. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/cli.py +128 -0
  12. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/__init__.py +0 -0
  13. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/auth.py +62 -0
  14. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/base.py +374 -0
  15. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/cache.py +59 -0
  16. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/endpoints.py +336 -0
  17. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/paging.py +65 -0
  18. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/retry.py +37 -0
  19. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/session.py +156 -0
  20. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/client/ws.py +150 -0
  21. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/config.py +315 -0
  22. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/coverage.py +71 -0
  23. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/errors.py +83 -0
  24. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/http_app.py +50 -0
  25. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/identity.py +192 -0
  26. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/integrations/__init__.py +0 -0
  27. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/integrations/langgraph.py +347 -0
  28. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/journal.py +208 -0
  29. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/knowledge/__init__.py +41 -0
  30. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/knowledge/concepts.md +62 -0
  31. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/knowledge/perps.md +55 -0
  32. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/knowledge/safety.md +63 -0
  33. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/knowledge/trading.md +52 -0
  34. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/logging_setup.py +18 -0
  35. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/models/__init__.py +0 -0
  36. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/models/base.py +146 -0
  37. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/models/clob.py +251 -0
  38. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/models/data.py +102 -0
  39. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/models/gamma.py +400 -0
  40. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/__init__.py +41 -0
  41. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/account.py +326 -0
  42. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/analytics.py +544 -0
  43. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/bridge.py +229 -0
  44. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/builder.py +242 -0
  45. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/combos.py +413 -0
  46. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/discovery.py +622 -0
  47. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/docs.py +153 -0
  48. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/market_data.py +226 -0
  49. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/perps_account.py +281 -0
  50. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/perps_extras.py +187 -0
  51. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/perps_market.py +523 -0
  52. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/perps_trading.py +953 -0
  53. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/registry.py +232 -0
  54. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/rewards.py +253 -0
  55. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/sports.py +128 -0
  56. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/streams.py +343 -0
  57. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/system.py +120 -0
  58. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/trading.py +776 -0
  59. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/ops/wallet.py +402 -0
  60. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/prompts.py +51 -0
  61. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/protocol.py +13 -0
  62. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/py.typed +0 -0
  63. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/redaction.py +66 -0
  64. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/resources.py +44 -0
  65. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/safety.py +224 -0
  66. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/server.py +68 -0
  67. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/__init__.py +19 -0
  68. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/clob.py +45 -0
  69. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/eip712.py +32 -0
  70. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/orders.py +369 -0
  71. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/perps.py +322 -0
  72. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/relayer.py +235 -0
  73. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/signing/wallets.py +121 -0
  74. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/tools.py +191 -0
  75. mcp_server_polymarket-0.1.0/src/mcp_server_polymarket/wallet_tx.py +265 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Marcell Tukora
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,28 @@
1
+ mcp-server-polymarket
2
+ Copyright (c) 2026 Marcell Tukora. Licensed under the MIT License (see LICENSE).
3
+
4
+ The signing code in src/mcp_server_polymarket/signing/ was written from the Polymarket
5
+ documentation (https://docs.polymarket.com). Where the documentation is silent, the protocol
6
+ details (field order of compact Perps operations, wallet address derivations, contract
7
+ addresses) follow the official Polymarket Python SDK, and the test vectors in
8
+ tests/fixtures/vectors/ are taken from or generated with that SDK:
9
+
10
+ polymarket-client (https://github.com/Polymarket/py-sdk)
11
+ Copyright (c) Polymarket. Licensed under the MIT License:
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software
14
+ and associated documentation files (the "Software"), to deal in the Software without
15
+ restriction, including without limitation the rights to use, copy, modify, merge, publish,
16
+ distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
17
+ Software is furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all copies or
20
+ substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
23
+ BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
25
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
27
+
28
+ This project is not affiliated with or endorsed by Polymarket.
@@ -0,0 +1,528 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-server-polymarket
3
+ Version: 0.1.0
4
+ Summary: MCP server and LangGraph tools for the Polymarket API: prediction markets and perps, market data, accounts and gated trading. Unofficial, not affiliated with Polymarket.
5
+ Keywords: polymarket,prediction-markets,perps,perpetual-futures,mcp,model-context-protocol,langgraph,langchain,clob,trading
6
+ Author: Marcell Tukora
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ License-File: NOTICE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: Financial and Insurance Industry
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Office/Business :: Financial :: Investment
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Classifier: Typing :: Typed
21
+ Requires-Dist: httpx2[ws]>=2.16
22
+ Requires-Dist: mcp>=2.3,<3
23
+ Requires-Dist: pydantic>=2.12
24
+ Requires-Dist: pydantic-settings>=2.10
25
+ Requires-Dist: starlette>=0.48
26
+ Requires-Dist: uvicorn>=0.31.1
27
+ Requires-Dist: langchain>=1.4.6 ; extra == 'langgraph'
28
+ Requires-Dist: langchain-core>=1.0 ; extra == 'langgraph'
29
+ Requires-Dist: langgraph>=1.2 ; extra == 'langgraph'
30
+ Requires-Dist: eth-account>=0.13 ; extra == 'signing'
31
+ Requires-Dist: eth-abi>=5 ; extra == 'signing'
32
+ Requires-Dist: msgpack>=1 ; extra == 'signing'
33
+ Requires-Python: >=3.11
34
+ Project-URL: Homepage, https://github.com/tukorama/mcp-server-polymarket
35
+ Project-URL: Repository, https://github.com/tukorama/mcp-server-polymarket
36
+ Project-URL: Issues, https://github.com/tukorama/mcp-server-polymarket/issues
37
+ Project-URL: Changelog, https://github.com/tukorama/mcp-server-polymarket/blob/main/CHANGELOG.md
38
+ Provides-Extra: langgraph
39
+ Provides-Extra: signing
40
+ Description-Content-Type: text/markdown
41
+
42
+ <!-- mcp-name: io.github.tukorama/mcp-server-polymarket -->
43
+
44
+ # MCP server and LangGraph tools for Polymarket
45
+
46
+ [![PyPI](https://img.shields.io/pypi/v/mcp-server-polymarket)](https://pypi.org/project/mcp-server-polymarket/)
47
+ [![CI](https://github.com/tukorama/mcp-server-polymarket/actions/workflows/ci.yml/badge.svg)](https://github.com/tukorama/mcp-server-polymarket/actions/workflows/ci.yml)
48
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/tukorama/mcp-server-polymarket/blob/main/LICENSE)
49
+
50
+ `mcp-server-polymarket` is a Model Context Protocol (MCP) server for the
51
+ [Polymarket](https://polymarket.com) APIs, covering both **Predictions** (Gamma, CLOB, Data API,
52
+ Relayer, Bridge, Combos and the WebSocket feeds) and **Perps** (perpetual futures, HTTP and
53
+ WebSocket). The same tools are packaged for LangGraph and LangChain. Reading needs no account.
54
+ Trading and transfers exist too, switched off until you turn them on.
55
+
56
+ > [!WARNING]
57
+ > Unofficial, and not affiliated with Polymarket. Orders and transfers move real money and cannot
58
+ > be undone, and an agent can misread a market. Polymarket restricts trading in some countries and
59
+ > regions; check that you are allowed to trade where you are. Start with `dry_run` and small
60
+ > limits. This software comes with no warranty (see the license).
61
+
62
+ ## Why this exists
63
+
64
+ Pointing an agent at the Polymarket APIs goes wrong in a few predictable ways, and each one
65
+ shaped this package.
66
+
67
+ - **There are seven APIs and two hundred endpoints.** The tools are curated: one tool answers one
68
+ question (`get_quotes` reads best bid, ask, midpoint, spread, tick size and minimum size for any
69
+ number of tokens in one request) and toolsets keep rarely needed areas out of the context.
70
+ - **Responses are huge.** A single event can be 28 KB and a search result 80 KB. Tools return
71
+ trimmed, typed results with outcomes, prices and token ids paired up, and lists are paged.
72
+ - **Signing is easy to get subtly wrong.** Orders, Deposit Wallet batches and Perps operations are
73
+ signed locally, checked against the official SDK's test vectors, and never with a guessed wallet
74
+ type.
75
+ - **An agent should not be able to spend money by accident.** Writes are hidden until you enable
76
+ them, checked against per-order and daily USD limits and a price-sanity band, and confirmed by
77
+ the user with a description the server writes, not the model, which shows every signed
78
+ parameter. Withdrawals go only to addresses provably yours or on an allowlist, and a Combo
79
+ quote is signed only if its amounts match what the user confirmed.
80
+ - **Networks fail after sending.** A write whose outcome is unknown is journaled, an identical
81
+ new request is blocked, and `resend_write` resends the exact signed bytes, which Polymarket
82
+ deduplicates. Nothing that moves money is ever retried automatically.
83
+
84
+ ## Quick start
85
+
86
+ Reading markets, books, prices, positions and Perps data needs nothing but `uv` and the server.
87
+
88
+ ### Claude Code
89
+
90
+ ```bash
91
+ claude mcp add polymarket -- uvx mcp-server-polymarket
92
+ ```
93
+
94
+ ### Cursor
95
+
96
+ Add to `.cursor/mcp.json` (or `~/.cursor/mcp.json` globally):
97
+
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "polymarket": {
102
+ "command": "uvx",
103
+ "args": ["mcp-server-polymarket"]
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ ### Claude Desktop
110
+
111
+ ```json
112
+ {
113
+ "mcpServers": {
114
+ "polymarket": {
115
+ "command": "uvx",
116
+ "args": ["mcp-server-polymarket"]
117
+ }
118
+ }
119
+ }
120
+ ```
121
+
122
+ ### VS Code
123
+
124
+ Add to `.vscode/mcp.json`:
125
+
126
+ ```json
127
+ {
128
+ "servers": {
129
+ "polymarket": {
130
+ "type": "stdio",
131
+ "command": "uvx",
132
+ "args": ["mcp-server-polymarket"]
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ ### ChatGPT (Developer Mode / Remote MCP)
139
+
140
+ Start the server over Streamable HTTP with bearer-token protection and tunnel or host it over HTTPS
141
+ before pasting the endpoint URL into ChatGPT's Developer Mode connector settings:
142
+
143
+ ```bash
144
+ POLYMARKET_HTTP_BEARER_TOKEN=change-me uvx mcp-server-polymarket serve --transport streamable-http --host 0.0.0.0 --port 8000
145
+ ```
146
+
147
+ Now ask for something like "What does Polymarket give for a Fed cut in December, and how deep is
148
+ the book?" or "Show me BTC perp funding over the last week."
149
+
150
+ ## Trading
151
+
152
+ Trading needs the `signing` extra, your wallet's address and a signing key.
153
+
154
+ 1. **Install with signing.** Use `uvx --from "mcp-server-polymarket[signing]" mcp-server-polymarket`
155
+ wherever the examples say `uvx mcp-server-polymarket`.
156
+ 2. **Configure the key and wallet.** Put the private key in a file readable only by you and set
157
+ `POLYMARKET_PRIVATE_KEY_FILE` to its path, and `POLYMARKET_WALLET_ADDRESS` to your Polymarket
158
+ wallet (the address shown on polymarket.com, not the key's own address). The server works out
159
+ the wallet type from the two and refuses a mismatch.
160
+ 3. **Create CLOB credentials once**, in a terminal:
161
+
162
+ ```bash
163
+ uvx --from "mcp-server-polymarket[signing]" mcp-server-polymarket auth
164
+ ```
165
+
166
+ They are saved to `~/.config/mcp-server-polymarket/session.json`, readable only by you. The
167
+ private key is never written to disk by this package.
168
+ 4. **Turn trading on** in the server's environment: `POLYMARKET_ALLOW_TRADING=true`. Optionally
169
+ lower `POLYMARKET_MAX_ORDER_USD` (100 by default) and `POLYMARKET_MAX_DAILY_USD` (1000).
170
+ 5. **Check** with `mcp-server-polymarket status`, which lists what is configured and every hidden
171
+ tool with the step that would show it.
172
+
173
+ ```json
174
+ {
175
+ "mcpServers": {
176
+ "polymarket": {
177
+ "command": "uvx",
178
+ "args": ["--from", "mcp-server-polymarket[signing]", "mcp-server-polymarket"],
179
+ "env": {
180
+ "POLYMARKET_PRIVATE_KEY_FILE": "/Users/me/.config/polymarket/key",
181
+ "POLYMARKET_WALLET_ADDRESS": "0x...",
182
+ "POLYMARKET_ALLOW_TRADING": "true",
183
+ "POLYMARKET_MAX_ORDER_USD": "20"
184
+ }
185
+ }
186
+ }
187
+ }
188
+ ```
189
+
190
+ Your MCP client must support **elicitation** (asking the user a question mid-call), because every
191
+ order is confirmed there. A client without it gets a refusal, not a silent order.
192
+
193
+ **Use a session key for day-to-day trading.** On a Deposit Wallet, the owner key can do anything,
194
+ including withdrawing. A session key can trade but cannot move funds out. Authorise one with the
195
+ owner key, then run the server with the session key instead:
196
+
197
+ ```bash
198
+ mcp-server-polymarket auth --session-key 0xSESSION_KEY_ADDRESS
199
+ ```
200
+
201
+ and set `POLYMARKET_PRIVATE_KEY_FILE` to the session key and `POLYMARKET_SIGNER_ROLE=session_key`.
202
+ The `wallet` and transfer tools need the owner key and stay hidden.
203
+
204
+ **On-chain actions** (`setup_trading_approvals`, `split_position`, `merge_positions`,
205
+ `redeem_positions`, `deposit_to_perps`) go through Polymarket's gasless Relayer and need a Relayer
206
+ API key from your Polymarket account: `POLYMARKET_RELAYER_API_KEY` and
207
+ `POLYMARKET_RELAYER_API_KEY_ADDRESS`.
208
+
209
+ **Perps** need a separate session, created once:
210
+
211
+ ```bash
212
+ mcp-server-polymarket auth --perps # a trading key that cannot withdraw
213
+ mcp-server-polymarket auth --perps --read-only
214
+ ```
215
+
216
+ **Moving funds** (Perps deposits and withdrawals, bridge withdrawals) needs
217
+ `POLYMARKET_ALLOW_TRANSFERS=true` as well, is capped by `POLYMARKET_MAX_TRANSFER_USD`, and is
218
+ always confirmed, whatever `POLYMARKET_CONFIRM` says.
219
+
220
+ **A safe first run:** preview an order with `dry_run`, place a post-only order at the minimum size
221
+ far from the market and cancel it, and on Perps set the leverage you already have.
222
+
223
+ `mcp-server-polymarket logout` forgets stored credentials; `logout --revoke` also deletes the CLOB
224
+ API key on Polymarket, `logout --builder-key` revokes the builder key, and `logout --perps`
225
+ revokes and forgets the Perps session.
226
+
227
+ ## LangGraph and LangChain
228
+
229
+ The `langgraph` extra gives you plain LangChain tools in the same process, with no MCP server to
230
+ run. It also has a prebuilt agent.
231
+
232
+ ```bash
233
+ uv add "mcp-server-polymarket[langgraph,signing]"
234
+ ```
235
+
236
+ ```python
237
+ from mcp_server_polymarket.integrations.langgraph import (
238
+ create_polymarket_agent,
239
+ get_polymarket_tools,
240
+ )
241
+
242
+ agent = create_polymarket_agent("anthropic:claude-sonnet-5-5")
243
+ config = {"configurable": {"thread_id": "1"}}
244
+ result = await agent.ainvoke({"messages": [("user", "How likely is a Fed cut?")]}, config=config)
245
+
246
+ # Or take the tools and build your own graph:
247
+ tools = get_polymarket_tools(toolsets="auto,+sports", prefix="pm_")
248
+ ```
249
+
250
+ The tools work from sync and async graphs. When trading is enabled, every order or transfer pauses
251
+ the graph with `interrupt()`, carrying the same confirmation text the MCP server would show.
252
+ Resume with `Command(resume=True)` to go ahead; any other value declines. Interrupts need a
253
+ checkpointer, which the prebuilt agent creates in memory (pass your own, or `checkpointer=None` on
254
+ LangGraph Platform). `get_polymarket_tools()` leaves those tools out unless you pass
255
+ `include_gated=True`, because they only work inside a graph with a checkpointer. See
256
+ [examples/langgraph_agent.py](https://github.com/tukorama/mcp-server-polymarket/blob/main/examples/langgraph_agent.py)
257
+ and the LangGraph Platform app in
258
+ [examples/langgraph_app](https://github.com/tukorama/mcp-server-polymarket/tree/main/examples/langgraph_app).
259
+
260
+ To keep Polymarket in a separate process, connect over MCP instead. This route needs
261
+ `langchain[mcp]`, which LangChain still marks as beta.
262
+
263
+ ```python
264
+ from langchain.agents import create_agent
265
+ from langchain.mcp import MCPAdapter
266
+
267
+ config = {"mcpServers": {"polymarket": {"command": "uvx", "args": ["mcp-server-polymarket"]}}}
268
+ async with MCPAdapter(config) as adapter:
269
+ agent = create_agent("anthropic:claude-sonnet-5-5", await adapter.list_tools())
270
+ ```
271
+
272
+ `draw_mermaid(agent)` draws a graph with its Polymarket tools grouped by toolset and colored by
273
+ what they can change. The prebuilt agent without credentials:
274
+
275
+ ```mermaid
276
+ ---
277
+ config:
278
+ flowchart:
279
+ nodeSpacing: 24
280
+ rankSpacing: 12
281
+ padding: 8
282
+ ---
283
+ flowchart TB
284
+ subgraph agent["Agent graph"]
285
+ direction LR
286
+ n0([start])
287
+ n1["model"]
288
+ n2["tools"]
289
+ n3([end])
290
+ n0 --> n1
291
+ n1 -.-> n3
292
+ n1 -.-> n2
293
+ n2 -.-> n1
294
+ end
295
+ subgraph tools["Tools"]
296
+ direction TB
297
+ subgraph tools_row0[" "]
298
+ direction LR
299
+ subgraph tools_analytics["analytics"]
300
+ direction LR
301
+ 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
302
+ end
303
+ subgraph tools_perps_market["perps-market"]
304
+ direction LR
305
+ 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
306
+ end
307
+ subgraph tools_discovery["discovery"]
308
+ direction LR
309
+ 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
310
+ end
311
+ tools_analytics ~~~ tools_perps_market ~~~ tools_discovery
312
+ end
313
+ subgraph tools_row1[" "]
314
+ direction LR
315
+ subgraph tools_docs["docs"]
316
+ direction LR
317
+ tools_docs_read["search_docs<br/>read_doc"]:::read
318
+ end
319
+ subgraph tools_market_data["market-data"]
320
+ direction LR
321
+ 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
322
+ end
323
+ subgraph tools_system["system"]
324
+ direction LR
325
+ tools_system_read["get_service_status<br/>auth_status"]:::read
326
+ end
327
+ tools_docs ~~~ tools_market_data ~~~ tools_system
328
+ end
329
+ tools_row0 ~~~ tools_row1
330
+ end
331
+ agent -- tool calls --> tools
332
+ subgraph legend["Legend"]
333
+ direction TB
334
+ legend_read["read-only"]:::read
335
+ end
336
+ polymarket["Polymarket APIs"]:::external
337
+ tools -- HTTPS / WebSocket --> polymarket
338
+ tools ~~~ legend
339
+ classDef default fill:#64748b,fill-opacity:0.06,stroke:#64748b
340
+ classDef read fill:#64748b,fill-opacity:0.14,stroke:#64748b
341
+ classDef write fill:#d97706,fill-opacity:0.16,stroke:#d97706
342
+ classDef funds fill:#dc2626,fill-opacity:0.16,stroke:#dc2626,stroke-width:2px
343
+ classDef external fill-opacity:0,stroke-dasharray:5 4
344
+ classDef box fill:#64748b,fill-opacity:0.05,stroke:#64748b,stroke-opacity:0.45
345
+ classDef row fill:none,stroke:none
346
+ class agent,tools,tools_analytics,tools_perps_market,tools_discovery,tools_docs,tools_market_data,tools_system,legend box
347
+ class tools_row0,tools_row1 row
348
+ ```
349
+
350
+ ## Tools
351
+
352
+ There are 128 tools in 18 toolsets. Without credentials the default set exposes 49. Tools that need
353
+ credentials or a gate appear only when they are configured; `auth_status` and
354
+ `mcp-server-polymarket tools` explain the rest.
355
+
356
+ Choose toolsets with `POLYMARKET_TOOLSETS`: `auto` (the default), `all`, `predictions`, `perps`, a
357
+ list of names, or adjustments such as `auto,+sports,-docs`.
358
+
359
+ **Always available with `auto`**
360
+
361
+ | Toolset | Tools |
362
+ |---|---|
363
+ | `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` |
364
+ | `market-data` | `get_order_books`, `get_quotes`, `get_price_history`, `get_market_trading_info`, `list_order_book_markets`, `get_live_activity` |
365
+ | `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` |
366
+ | `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` |
367
+ | `system` | `get_service_status`, `auth_status` |
368
+ | `docs` | `search_docs`, `read_doc` (docs.polymarket.com only) |
369
+
370
+ **With credentials (`auto`)**
371
+
372
+ | Toolset | Needs | Tools |
373
+ |---|---|---|
374
+ | `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` |
375
+ | `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` |
376
+ | `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` |
377
+ | `wallet` | owner key + Relayer key + `ALLOW_TRADING` | `setup_trading_approvals`, `split_position`, `merge_positions`, `redeem_positions` |
378
+ | `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`\* |
379
+
380
+ **On request (`+name`)**
381
+
382
+ | Toolset | Tools |
383
+ |---|---|
384
+ | `sports` | `get_sports_metadata`, `list_teams`, `list_sports_results`, `watch_sports` |
385
+ | `rewards` | `list_reward_markets`, `get_maker_rebates`, `get_my_reward_earnings`, `list_my_reward_markets`, `get_my_order_scoring` |
386
+ | `streams` | `watch_market`, `watch_live_data`, `watch_perps_market` |
387
+ | `bridge` | `list_bridge_assets`, `get_bridge_quote`, `get_bridge_status`, `create_deposit_addresses`, `create_withdrawal_addresses` (transfers) |
388
+ | `combos` | `list_combo_markets`, `get_combo_request`, `plan_collateral_return`, `trade_combo`\*, `execute_collateral_return`\* (trading) |
389
+ | `builder` | `get_builder_leaderboard`, `list_builder_trades`, `list_builder_api_keys`, `list_relayer_api_keys`, `get_my_perps_builder`, `set_perps_builder_approval` (trading) |
390
+ | `perps-extras` | `get_perps_leaderboard`, `list_perps_competitions`, `get_perps_competition`, `get_perps_position_snapshots`, `get_my_perps_blp`, `set_perps_blp_enrollment` (trading) |
391
+
392
+ \* Experimental: the wire format comes from the documentation and has not been verified against
393
+ the live API.
394
+
395
+ `watch_*` tools open a WebSocket, collect events for a few seconds or up to a count, and return a
396
+ summary; they do not stream indefinitely.
397
+
398
+ Resources: `polymarket://perps/instruments`, `polymarket://markets/{slug}`, and reference pages
399
+ under `polymarket://docs/` (`concepts`, `trading`, `perps`, `safety`).
400
+
401
+ Prompts: `research_market`, `review_portfolio` and `plan_perps_trade`. None of them trades.
402
+
403
+ ### API coverage
404
+
405
+ Every operation in the published OpenAPI and AsyncAPI specifications listed in
406
+ [docs.polymarket.com/llms.txt](https://docs.polymarket.com/llms.txt), plus the routes the guides
407
+ describe, is either called by a tool, used by the CLI (key creation and revocation), or listed
408
+ with a reason in
409
+ [coverage.py](https://github.com/tukorama/mcp-server-polymarket/blob/main/src/mcp_server_polymarket/coverage.py).
410
+ A test checks this against a manifest generated from the specifications, and that the test suite
411
+ calls every endpoint. Deliberately left out: CLOB heartbeats (they need a five-second loop),
412
+ Combos market making (a 400 ms quote loop), and Perps `PATCH /v1/account/builder`, whose signed
413
+ payload is undocumented. The separate Polymarket US exchange is not covered.
414
+
415
+ ## Configuration
416
+
417
+ All settings are environment variables with the `POLYMARKET_` prefix. A `.env` file in the
418
+ working directory can set only the harmless ones (`TOOLSETS`, `HTTP_TIMEOUT`, `LOG_LEVEL`).
419
+ Keys, wallet, credentials, gates, limits, confirmation mode, allowlist, builder settings, service
420
+ URLs, file paths and the bearer token have to be set in the real environment (for example the
421
+ client's `env` block), so that a file in a project directory cannot swap the signing key, redirect
422
+ funds or turn trading on.
423
+
424
+ | Variable | Default | Purpose |
425
+ |---|---|---|
426
+ | `PRIVATE_KEY_FILE`, `PRIVATE_KEY` | | Signing key (owner or session key). Prefer the file |
427
+ | `WALLET_ADDRESS` | | Your Polymarket wallet. Needed for anything signed |
428
+ | `SIGNER_ROLE` | `owner` | `session_key` when the key is a Deposit Wallet session key |
429
+ | `SIGNATURE_TYPE` | detected | 0 EOA, 1 Proxy, 2 Safe, 3 Deposit Wallet; only checked against detection |
430
+ | `API_KEY`, `API_SECRET`, `API_PASSPHRASE`, `ADDRESS` | | Existing CLOB credentials, for account reads without a private key |
431
+ | `RELAYER_API_KEY`, `RELAYER_API_KEY_ADDRESS` | | Relayer key for wallet transactions |
432
+ | `PERPS_PROXY`, `PERPS_SECRET`, `PERPS_PROXY_KEY` | | An existing Perps session instead of `auth --perps` |
433
+ | `TOOLSETS` | `auto` | See [Tools](#tools) |
434
+ | `ALLOW_CANCEL` | `false` | Cancel tools only |
435
+ | `ALLOW_TRADING` | `false` | Orders, leverage, wallet transactions (includes cancel) |
436
+ | `ALLOW_TRANSFERS` | `false` | Deposits, withdrawals and transfers |
437
+ | `CONFIRM` | `elicit` | `none` skips the confirmation question for trading, never for transfers |
438
+ | `MAX_ORDER_USD` | `100` | Per order. `0` blocks, `unlimited` lifts |
439
+ | `MAX_DAILY_USD` | `1000` | Per UTC day, separately for orders, Perps orders and transfers |
440
+ | `MAX_PERPS_ORDER_USD` | `500` | Per Perps order (reduce-only orders are exempt) |
441
+ | `MAX_PERPS_LEVERAGE` | `5` | Highest leverage `set_perps_leverage` accepts |
442
+ | `MAX_TRANSFER_USD` | `100` | Per transfer |
443
+ | `MAX_PRICE_DEVIATION` | `0.10` | Refuse prices this far through the book: 0.10 pUSD for prediction markets, 10% of the mark for Perps |
444
+ | `TRANSFER_ALLOWLIST` | | Comma-separated recipients other than your own wallet |
445
+ | `BUILDER_API_KEY`, `BUILDER_SECRET`, `BUILDER_PASSPHRASE`, `BUILDER_CODE`, `PERPS_BUILDER` | | Builder program attribution |
446
+ | `SESSION_FILE`, `PERPS_SESSION_FILE`, `JOURNAL_FILE` | `~/.config/mcp-server-polymarket/…` | Stored credentials and the write journal |
447
+ | `CACHE_DIR` | `~/.cache/mcp-server-polymarket` | Instrument, label and docs cache |
448
+ | `HTTP_TIMEOUT` | `20` | Seconds per HTTP request |
449
+ | `HTTP_BEARER_TOKEN` | | Required by the HTTP transport on a non-local address |
450
+ | `LOG_LEVEL` | `INFO` | Logs go to stderr |
451
+ | `GAMMA_URL`, `CLOB_URL`, `DATA_URL`, `PERPS_URL`, … | Polymarket's | Service endpoints, `https` and `wss` only |
452
+
453
+ On Windows the two directories are `%APPDATA%\mcp-server-polymarket` and
454
+ `%LOCALAPPDATA%\mcp-server-polymarket`, and files are protected by your user profile rather than
455
+ POSIX permissions.
456
+
457
+ To serve over HTTP:
458
+
459
+ ```bash
460
+ POLYMARKET_HTTP_BEARER_TOKEN=change-me mcp-server-polymarket serve --transport streamable-http --host 0.0.0.0
461
+ ```
462
+
463
+ The server refuses a non-local address without a token. `/health` stays open for probes. Do not
464
+ expose a server with trading enabled to anyone you would not hand your wallet.
465
+
466
+ ## How it behaves
467
+
468
+ **Confirmation.** Each order, wallet transaction and transfer is described by the server from
469
+ market data (outcome name, price, shares, cost, wallet, recipient) and confirmed by the user before
470
+ it is signed. Declining returns `declined`; nothing is sent. Cancels are not confirmed.
471
+
472
+ **Checks before signing.** Tick size (off-tick prices are refused, never rounded), minimum size,
473
+ distance from the best price or mark, per-order and daily limits, leverage cap, Protocol V1/V2
474
+ exchange version, and Polymarket's geoblock check, which fails closed. Missing balance or
475
+ allowance is reported, never fixed by an automatic approval.
476
+
477
+ **Unknown outcomes.** If the connection drops after a write is sent, the tool returns
478
+ `unknown` with a `request_id`. An identical request is blocked until you check
479
+ (`list_unconfirmed_writes`) and either resend the same bytes (`resend_write`) or let it expire
480
+ after 15 minutes. The journal keeps signed bodies only for those writes.
481
+
482
+ **Retries.** Reads retry with backoff and honour `Retry-After`. Orders, cancels and transfers are
483
+ never retried automatically.
484
+
485
+ **Long calls.** Claude Desktop has been reported to cancel stdio tool calls after about a minute,
486
+ so for that client waits (Relayer confirmations, `watch_*`) are capped at 45 seconds. A Relayer
487
+ transaction still unconfirmed then returns `pending` with an id for `get_relayer_transaction`.
488
+
489
+ **What is never logged.** Private keys, API secrets, passphrases, HMAC signatures and signed
490
+ bodies are masked in logs and errors by exact value. Market descriptions and comments are
491
+ stripped of control and bidirectional characters, and the agent guide marks them as untrusted.
492
+
493
+ ## Limitations
494
+
495
+ - Read tools have been run against the live APIs. Order placement, cancels, wallet transactions,
496
+ Perps operations and transfers have been tested against recorded responses, the official SDK's
497
+ signing test vectors and a differential test against the SDK, but **not with real funds**. The
498
+ tools marked experimental are less proven still. Make your first live writes small.
499
+ - Polymarket changes its APIs often. `live.yml` runs the live read tests, the manifest check and
500
+ the SDK comparison weekly. Protocol V2 markets start on 2026-11-23; the V2 exchange contracts
501
+ and position ids are supported but could not be tried before launch.
502
+ - Wallet transactions support Deposit Wallets only. Proxy and Safe wallets can trade on the CLOB
503
+ but cannot use the `wallet` toolset, because their Relayer signing is not documented. An EOA
504
+ (signature type 0) cannot use the gasless Relayer at all.
505
+ - Session keys cannot trade Combos.
506
+ - `session.json` and `perps_session.json` are plaintext protected by file permissions. Keep the
507
+ private key in a file of its own, or in your own secret store passed through the environment.
508
+ - Check that your use of automated trading complies with Polymarket's terms and the law where you
509
+ are.
510
+
511
+ ## Development
512
+
513
+ To point a client at a checkout, use
514
+ `uvx --from "/path/to/mcp-server-polymarket[signing]" mcp-server-polymarket`, or
515
+ `uv add --editable ../mcp-server-polymarket` from your LangGraph project. Start with the guided
516
+ codebase tour in
517
+ [onboarding/](https://github.com/tukorama/mcp-server-polymarket/tree/main/onboarding), and see
518
+ [CONTRIBUTING.md](https://github.com/tukorama/mcp-server-polymarket/blob/main/CONTRIBUTING.md)
519
+ for contributor workflows.
520
+
521
+ The protocol details follow Polymarket's documentation and the MIT-licensed
522
+ [polymarket-client](https://pypi.org/project/polymarket-client/) SDK, which is used as a test
523
+ oracle; see
524
+ [NOTICE](https://github.com/tukorama/mcp-server-polymarket/blob/main/NOTICE).
525
+
526
+ ## License
527
+
528
+ [MIT](https://github.com/tukorama/mcp-server-polymarket/blob/main/LICENSE)