polymarket-paper-trader

What it does

This is a practice account for Polymarket, and since 0.4.13's README also for Kalshi, run as a local Python MCP server. Market lists, prices and order books come live from the two exchanges' public APIs. The orders themselves are only simulated. A buy eats through the real ask levels and pays the fee from that market's published schedule (Kalshi uses each series' own curve). Once a market closes, you can settle it and collect a simulated $1 for each winning share. You never connect a wallet or a key, and nothing is sent to either exchange.

The server registers 33 tools in `pm_trader/mcp_server.py` at v0.4.13. With them an assistant opens an account (10,000 dollars unless told otherwise), searches and browses Polymarket markets and reads an order book. It can also list Kalshi markets and their books. Trading covers market buys and sells plus resting limit orders, and it tracks the portfolio, trade history and stats such as ROI, win rate, Sharpe and drawdown. Named accounts sit side by side. Card tools turn results into head-to-head comparisons, a local top 10 or text to post. A Kalshi market is traded by giving `kalshi:<TICKER>` as the market.

Accounts are SQLite files under `~/.pm-trader/<account>`. The MCP server builds that path from your home folder and does not read the `PM_TRADER_DATA_DIR` setting the README lists, which only the `pm-trader` command line uses. Code caps market lists at 100 per call (`search_markets` returns 10 by default, the other list tools 20) and trade history at 1,000 rows. The server also ships a `trading_playbook` prompt with the makers' trading guide, and two HTML views that MCP Apps hosts show for `portfolio`, `stats` and `get_market`.

What it needs

The documented launch command uses uvx, so uv must be installed. Or run `pip install polymarket-paper-trader` and start `pm-trader-mcp` directly. It needs network access to the public Polymarket and Kalshi APIs, which take no key. Remote mode is optional: you run the HTTP server yourself and, for sign-in, an OAuth/OIDC issuer you operate.

Limits

• Not covered Paper trading only: it cannot place real orders, hold funds or connect a wallet on Polymarket or Kalshi
• Limit Its docs say real execution adds queue position, latency and counterparty behaviour that the simulator leaves out
• Limit Resting limit orders fill only when check_orders is called
• Size cap Market lists are capped at 100 per call and trade history at 1,000 rows in code
• Not covered backtest and pk_battle only load strategy modules under the examples. package, and are removed over streamable-http
• Limit Without all three auth settings, streamable-http has no sign-in and every caller shares the same accounts
• Rate limit Remote mode with sign-in allows 60 tool calls a minute and 20 accounts per user by default
• Limit Remote mode deletes user folders idle for 90 days by default (PM_TRADER_PRUNE_IDLE_DAYS, 0 turns it off)
• Limit No hosted endpoint and no published image: the Dockerfile must be built yourself and serves HTTP only

Paper trading only: it cannot place real orders, hold funds or connect a wallet, and its own docs note that real execution adds queue position, latency and counterparty behaviour the simulator does not model. Limit orders only fill when `check_orders` is called. `backtest` and `pk_battle` are removed when serving over streamable-http. That HTTP transport has no authentication unless all three of `--auth-issuer`, `--auth-audience` and `--resource-url` are given, and without them every caller shares the same accounts. There is no hosted endpoint and no published container image; the Dockerfile must be built yourself and serves HTTP only.

Who it suits

Suits developers who want an assistant or a trading strategy to practise on Polymarket or Kalshi markets, or to compare models and accounts, with no money at stake. It runs locally, needs no key, and its writes only touch its own local account files. It is a poor fit for anyone who wants to trade for real, since it has no wallet or order submission at all, and it is published by neither exchange. Pick the HTTP mode only if your host cannot run a local stdio server, and then keep it on 127.0.0.1 or behind the OAuth mode.