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

| Area | Requires L2 / wallet | |------|----------------------| | Resources (polymarket://status, polymarket://config, polymarket://rate-limits) | Partial (status reflects auth) | | Market discovery (search, trending, categories, …) | No | | Market analysis (order book, prices, volume, …) | No (some calls use anonymous CLOB) | | Trading (place/cancel orders, smart trade, …) | Yes | | Portfolio (positions, PnL, history, …) | Yes | | Realtime WebSocket subscriptions | User streams need API credentials + auth |

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

DEMO_MODE=true skips a funded wallet. Gamma/Data discovery (including get_positions) remains available unless a tool explicitly needs credentials.
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).

MCP Servers