Setup

From the repo root:

git clone https://github.com/japp-fi/polymarket-mcp-server
cd polymarket-mcp-server

npm install
npm run build

Development (TypeScript directly):

npm run dev

Production (compiled):

npm start

Configuration

The server reads environment variables via dotenv (place a .env file in the working directory).

.env.example

Copy .env.example to .env and fill in values. Never commit real keys.

Modes

1. DEMO_MODE=true skips a funded wallet. Gamma/Data discovery (including get_positions) remains available unless a tool explicitly needs credentials.

2. Live trading

   Provide POLYGON_ADDRESS plus POLYGON_PRIVATE_KEY (or POLYMARKET_PRIVATE_KEY, IQAI-compatible alias). Optionally set POLYGON_RPC_URL (defaults https://polygon-rpc.com) for on-chain approve_allowances / redeem_positions.

Proxy wallets (IQAI-style)

Browser-wallet users commonly fund a Polymarket proxy / Safe separately from the EIP-1193 signer. Mirror their env:

• POLYMARKET_FUNDER or FUNDER_ADDRESS – USDC custodian address shown in the Polymarket UI (0x…)
• SIGNATURE_TYPE – 2 selects POLY_GNOSIS_SAFE ordering (the default whenever a non-empty POLYMARKET_FUNDER is present). Use 1 (POLY_PROXY) for Magic-email flows.

Environment reference (extras)

| Variable | Meaning | |---------|---------| | POLYGON_RPC_URL | JSON-RPC endpoint for Polygon (on-chain tooling + faster reads) | | POLYMARKET_PRIVATE_KEY | Alias of POLYGON_PRIVATE_KEY | | CHAIN_ID | Overrides POLYMARKET_CHAIN_ID when supplied | | CLOB_API_BASE | Overrides / fills CLOB_API_URL (IQAI spelling) |

Explicit CLOB API credentials (optional)

Polymarket’s ApiKeyCreds have three separate fields: key, secret, and passphrase. Set:

| Variable | Maps to | |----------|---------| | POLYMARKET_API_KEY | API key (key) | | POLYMARKET_SECRET | HMAC secret (secret) | | POLYMARKET_PASSPHRASE | Passphrase (passphrase) |

If you previously used POLYMARKET_API_KEY_NAME as the key string, you can still set only that (with POLYMARKET_API_KEY empty) — it is treated as an alias for key. You must also set POLYMARKET_SECRET and POLYMARKET_PASSPHRASE; the secret and passphrase are not interchangeable.

If any of the three are missing, the server falls back to derive from the wallet (recommended in the official CLOB client README).

Safety and limits (optional)

Defaults are in src/config.ts. Notable env vars:

• MAX_ORDER_SIZE_USD, MAX_TOTAL_EXPOSURE_USD, MAX_POSITION_SIZE_PER_MARKET
• MIN_LIQUIDITY_REQUIRED, MAX_SPREAD_TOLERANCE
• ENABLE_AUTONOMOUS_TRADING, REQUIRE_CONFIRMATION_ABOVE_USD, AUTO_CANCEL_ON_LARGE_SPREAD
• CLOB_API_URL, GAMMA_API_URL (defaults point at Polymarket production)

Wire it to Cursor (or any MCP client)

This server speaks stdio MCP. Example for Cursor mcp.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "node",
      "args": ["/absolute/path/to/polymarket-mcp-server/dist/server.js"],
      "env": {
        "DEMO_MODE": "true"
      }
    }
  }
}

For live trading, remove DEMO_MODE and pass POLYGON_PRIVATE_KEY (or POLYMARKET_PRIVATE_KEY), POLYGON_ADDRESS, optional POLYGON_RPC_URL / POLYMARKET_FUNDER / SIGNATURE_TYPE, and optionally explicit CLOB credentials via env or a .env next to the process working directory.

Operational notes

• Stdio only: log lines meant for operators go to stderr; JSON-RPC uses stdout. Do not pipe debug output into stdout in production.
• WebSockets: the server attempts CLOB and live-data WebSocket connections at startup; failures are logged and discovery/analysis via HTTP usually still works.
• Security: keys grant account access — use least privilege, .env only on trusted machines, and review Polymarket’s own docs for key rotation.

License

MIT (see package metadata).