Polymarket Agent MCP

MCP server that lets a local AI client read Polymarket markets and, when you turn live mode on, place orders with your wallet. Version 1.7.0. Node.js 20 or newer. MIT license.

The process starts in preview. Preview writes simulated trades to a local SQLite file and does not sign or send orders. Live mode signs CLOB orders with POLY_PRIVATE_KEY and posts them to https://clob.polymarket.com. One process, one database, one wallet. It is a single-operator tool.

Stdio is the transport for Claude Code, Cursor, and other local MCP clients. HTTP is optional and should stay on a private network.

Capability details: PERMISSIONS.md and SECURITY.md.

What a call does

1. The client invokes a tool. Inputs are checked with Zod.

2. Read tools call the public Polymarket APIs, or ESPN when the tool is wta.discover.

3. Trade tools run the safety checks, then the daily budget check.

4. In preview, the trade row is stored as simulated.

5. In live, TradeExecutor builds a CLOB client, derives API credentials from the signing key, and calls createAndPostOrder. The position row is stored as executed only after the CLOB accepts the order.

config.go_live flips the running process to live after confirm: true, and only if the live credentials are set. A restart returns to COPY_MODE from the environment.

Related MCP server: Crocodile

Install

npm install -g polymarket-agent-mcp

From this repository:

git clone https://github.com/polytutor-ai/polymarket-mcp-agent.git
cd polymarket-agent-mcp
npm install
npm run build
npm test

Claude Code, in ~/.claude/settings.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["polymarket-agent-mcp"]
    }
  }
}

Copy .env.example to .env beside the package when you want a budget other than the defaults, or when you want live trading. The loader reads .env from the package root, not from the process working directory.

Modes

Live startup requires all four of these to be non-empty:

POLY_PRIVATE_KEY=
POLY_API_KEY=
POLY_API_SECRET=
POLY_API_PASSPHRASE=
POLY_FUNDER_ADDRESS=
COPY_MODE=live

The executor signs with POLY_PRIVATE_KEY and then calls createOrDeriveApiKey(). The CLOB client is constructed with signature type 1 and POLY_FUNDER_ADDRESS as the funder, which matches a Polymarket proxy wallet. CHAIN_ID defaults to 137 (Polygon).

Keys stay in the process config. They are not written to SQLite. Error text that looks like a long hex key is redacted before it is logged. The designated order host is clob.polymarket.com.

Copy monitor

monitor.start polls watched wallets on an interval (default 30 seconds, allowed range 10–300). Each tick reads recent BUY activity from data-api.polymarket.com. A trade is eligible when it is newer than the monitor’s max age and its USDC size is at least MIN_CONVICTION (default $3). The copy size is then limited by the remaining daily budget (DAILY_BUDGET, default $20).

monitor.stop clears that loop. The watchlist survives in SQLite.

watchlist.rebalance drops watched addresses that fail the performance rules in that tool. traders.backtest replays a wallet’s past trades locally and does not send orders.

Safety limits

config.safety_limits stores limits in the config table. Defaults until you change them:

orders.buy rejects a ticket that would exceed max order size, total recorded exposure, or the per-market total. Market-quality checks used by buy and the monitor look at spread, depth, and price range separately. Stop-loss and take-profit levels are stored with positions.set_exit_rules and evaluated when something calls positions.check_exits. They are not a background loop of their own.

Network

HTTP reads use a 10 second timeout and up to two retries. The websocket sends a public market subscription. It does not send the wallet key. There is no analytics or update-check client in this package.

HTTP transport

HTTP starts when the process is given --http or when PORT is set. The Docker image does both: CMD is node dist/index.js --http and PORT=3000.

node dist/index.js --http
PORT=8080 node dist/index.js

MCP_API_KEY, when set, requires Authorization: Bearer <token> on /mcp. When it is unset, /mcp accepts any caller who can open the port. The listen socket is all interfaces. Keep HTTP on localhost, or set MCP_API_KEY and do not publish the port.

docker build -t polymarket-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -v mcp-data:/app/data \
  -e COPY_MODE=preview \
  -e DAILY_BUDGET=20 \
  -e MCP_API_KEY=replace-me \
  polymarket-mcp

A release image is published as ghcr.io/demwick/polymarket-agent-mcp:1.7.0.

docker compose up builds the local Dockerfile, mounts ./data at /app/data, and sets preview mode. The Compose file does not publish port 3000. The container still runs the HTTP command from the Dockerfile. Add a ports mapping yourself if you want to reach it from the host.

SQLite path: DB_PATH, default ./copytrader.db, or /app/data/copytrader.db in the image. The file holds the watchlist, trades, daily budget, safety config, exit rules, and agent-cycle notes. It does not hold the signing key.

Configuration

config.set can change daily_budget and min_conviction in the database while the process is running. It cannot change the signing key or COPY_MODE.

Tools

Forty-eight tools are registered in src/index.ts. Names below are the MCP tool ids.

Markets

Traders and copy

Orders and positions

Portfolio and config

Two prompts are registered for clients that support them: daily-trading-cycle and evaluate-trader. They return a checklist of tool calls. They do not place orders by themselves.

Layout

src/
  index.ts           # tool registration, stdio, HTTP
  constants.ts       # Polymarket base URLs
  tools/             # one module per tool
  services/          # executor, monitor, books, backtest, WTA
  db/                # SQLite schema and queries
  utils/             # config, safety, fetch, logging

Logs go to stderr so stdio MCP can keep stdout for JSON-RPC. The last 500 lines are also kept in memory and can be forwarded to the MCP client as logging messages.

Scripts

npm run build          # tsc
npm start              # node dist/index.js
npm run start:http     # node dist/index.js --http
npm test               # vitest
npx tsc --noEmit       # typecheck; CI runs this before publish

package.json engines require Node.js >=20. prepublishOnly runs the TypeScript build. The only install scripts in the lockfile are better-sqlite3 (native module) and optional macOS fsevents.