polymarket-mcp

The leading MCP server for Polymarket APIs and trading/relayer workflows.

Features

• MCP stdio server using @modelcontextprotocol/sdk.
• Public discovery tools for markets/events/search (list_markets, get_market, list_events, get_event, search).
• Batched market-data tools (get_order_books, get_prices, get_midpoints, get_spreads, get_last_trade_prices, get_price_history).
• Canonical auth/trading wrappers (ensure_api_key, prepare_order, place_order, cancel_orders, rewards/account wrappers).
• Relayer and builder-relayer execution tools.
• Bridge tools and unified transaction builder (build_transactions).
• Canonical wrappers expose rich listTools() schemas/descriptions so agents can discover required fields, auth level (L1 vs L2), and destructive confirmation guards from MCP introspection.
• Safe, structured JSON tool envelopes.
• Runtime resources (polymarket://status, polymarket://contracts, polymarket://endpoints) plus market resource templates.
• Agent-ready prompts for market analysis, portfolio review, and execution checklist.
• Multi-layer test matrix (smoke, integration, unit).

Install (published package)

Global install:

npm install -g @carbon-copy/polymarket-mcp

One-off execution without global install:

npx -y @carbon-copy/polymarket-mcp

MCP client setup (recommended)

Claude CLI one-command setup:

claude mcp add polymarket -- npx -y @carbon-copy/polymarket-mcp

Claude Desktop MCP config (stdio via npx):

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "@carbon-copy/polymarket-mcp"],
      "env": {
        "POLYMARKET_CHAIN_ID": "137"
      }
    }
  }
}

Installed binary variant (after global install):

{
  "mcpServers": {
    "polymarket": {
      "command": "polymarket-mcp",
      "env": {
        "POLYMARKET_CHAIN_ID": "137"
      }
    }
  }
}

Local development (run from source)

Use repository checkout when developing or modifying the server:

git clone https://github.com/CarbonCopyInc/polymarket-mcp.git
cd polymarket-mcp
npm install
npm run build
node dist/index.js

Build

npm run build

Test

npm test

npm test runs npm run build and then executes all tests under test/**/*.test.mjs.

Test layers:

• test/smoke/stdio.smoke.test.mjs
  • Top-level real-server MCP verification over stdio transport.
  • Confirms only the canonical simplified tool inventory is exposed.
  • Exercises representative public/auth/bridge/builder/relayer calls and destructive guardrails.
• test/integration/tool-flows.integration.test.mjs
  • Focused tool-layer integration with stubbed clients for mapper/guard/normalization behavior.
  • Covers canonical order/reward/relayer/builder/tx-builder behavior.
• test/integration/clients.integration.test.mjs
  • Polymarket client integration around auth cache invalidation, builder-relayer tx type handling, and bridge base-url normalization.
• test/integration/live-env-gated.integration.test.mjs
  • External-network integration smoke for authenticated, relayer, and bridge flows.
  • Assertions are env-gated and network-tolerant: missing credentials or transient network failures become diagnostics, not hard failures.
• test/unit/env-config.unit.test.mjs
• test/unit/helpers.unit.test.mjs
• test/unit/schemas-results.unit.test.mjs
  • Unit coverage for env/config normalization, canonical schema/result helpers, confirm guard logic, bigint parsing/stringification, and transaction-shape utilities.

Run the server (local repository workflow)

Repo build output:

npm run build
npm start

Global npm install:

polymarket-mcp

One-off without global install:

npx -y @carbon-copy/polymarket-mcp

All commands above start the MCP server on stdio via dist/index.js.

Publish (maintainers)

npm run build
npm test
npm publish

The published package includes only dist/, README.md, and LICENSE (plus npm-required metadata files).

Environment variables

Core runtime:

• POLYMARKET_RPC_URL (optional)
• POLYMARKET_CHAIN_ID (default: 137, supports 80002)
• POLYMARKET_SIGNATURE_TYPE (default: 0)
• POLYMARKET_RELAYER_URL (default: https://relayer-v2.polymarket.com)
• POLYMARKET_RELAYER_TX_TYPE (optional)
• POLYMARKET_CLOB_URL (default: https://clob.polymarket.com)
• POLYMARKET_GAMMA_URL (default: https://gamma-api.polymarket.com)
• POLYMARKET_BRIDGE_URL (default: https://bridge.polymarket.com)

Auth-related env names:

• POLYMARKET_ADDRESS
• POLYMARKET_PRIVATE_KEY
• POLYMARKET_FUNDER_ADDRESS
• POLYMARKET_API_KEY
• POLYMARKET_API_SECRET
• POLYMARKET_API_PASSPHRASE
• POLYMARKET_BUILDER_API_KEY
• POLYMARKET_BUILDER_API_SECRET
• POLYMARKET_BUILDER_API_PASSPHRASE
• POLYMARKET_BUILDER_AUTH_HEADER
• POLYMARKET_GEOBLOCK_TOKEN
• POLYMARKET_USER_AGENT

Operator notes

• If auth env is absent, authenticated checks are intentionally skipped (with diagnostics) in smoke/integration tests.
• If builder credentials are absent, builder-relayer live integration checks are skipped.
• Live-network integration assertions are env-gated and external-dependency tolerant.
• Public stdio smoke checks remain mandatory and are always executed.