Polymarket MCP Server

Model Context Protocol (MCP) server for Polymarket: market discovery and analysis via public APIs; optional authenticated trading and portfolio tools when your wallet derives (or supplies) CLOB L2 credentials.

Requires Node.js 18+.

Features

Trading and portfolio handlers are registered only after the CLOB client has L2 credentials (derived from your signing key via deriveApiKey with a createApiKey fallback, or supplied manually — see below).

This codebase does not bundle @jsr/hk__polymarket or fastmcp; Gamma/Data API flows use plain HTTP like the rest of the server.

Feature parity additions inspired by @iqai/mcp-polymarket include: POLYGON_RPC_URL, POLYMARKET_PRIVATE_KEY (alias), CHAIN_ID / CLOB_API_BASE, POLYMARKET_FUNDER / FUNDER_ADDRESS, SIGNATURE_TYPE (defaults to GNOSIS-safe style when a funder is set), Gamma tools (get_market_by_slug, get_event_by_slug, gamma_public_search, tag listing, paginated markets), get_positions (Data API), CLOB get_balance_allowance / update_balance_allowance, place_limit_order_token / place_market_order_token, approve_allowances, redeem_positions, optional approval checks before mutating trades, and NegRisk-aware Polygon contract addresses.

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)

Explicit CLOB API credentials (optional)

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

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