Polymarket MCP Server

Give your AI assistant direct access to Polymarket — market discovery, order book analysis, portfolio tracking, and optional live trading — through the Model Context Protocol (MCP). Works with Cursor, Claude Desktop, and any MCP-compatible client.

---

What You Get

Connect Polymarket to your AI workflow without writing glue code for every API call.

Capability	Demo mode	Live (wallet)
Market search, trending, categories	✅	✅
Order book, prices, volume analysis	✅	✅
Positions & PnL (Data API)	✅	✅
Place / cancel orders, smart trade	❌	✅
Portfolio history & balance	❌	✅
WebSocket live subscriptions	Partial	✅ (with credentials)
On-chain approve / redeem	❌	✅

Trading and portfolio tools register only after L2 credentials are available — derived from your signing key or supplied manually.

---

Why This Server?

• Cursor-ready — stdio MCP, drop into mcp.json and go
• Safety limits built in — max order size, exposure caps, spread tolerance, confirmation thresholds
• Proxy wallet support — Gnosis Safe / Polymarket funder flows (SIGNATURE_TYPE, POLYMARKET_FUNDER)
• NegRisk-aware — correct Polygon contract addresses for multi-outcome markets
• No heavy SDK lock-in — Gamma/Data API via plain HTTP; official @polymarket/clob-client for trading
• IQAI-compatible env aliases — POLYMARKET_PRIVATE_KEY, CLOB_API_BASE, FUNDER_ADDRESS, and more

---

Quick Start

1. Install & build

git clone https://github.com/hydra-node/polymarket-mcp-server.git
cd polymarket-mcp-server
npm install
npm run build

2. Demo mode (no wallet)

cp .env.example .env
# Set DEMO_MODE=true
npm start

3. Wire to Cursor

Add to your Cursor MCP config (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 wallet env vars (see Configuration below).

---

Configuration

The server reads .env via dotenv. Never commit real keys.

Modes

Demo mode — DEMO_MODE=true skips a funded wallet. Discovery and analysis tools work; trading tools are not registered.

Live trading — provide:

POLYGON_ADDRESS=0x...
POLYGON_PRIVATE_KEY=0x...
# or POLYMARKET_PRIVATE_KEY (alias)

# Optional but recommended
POLYGON_RPC_URL=https://polygon-rpc.com
POLYMARKET_FUNDER=0x...          # USDC custodian from Polymarket UI
SIGNATURE_TYPE=2                 # 2 = Gnosis Safe (default when funder set)

Explicit CLOB credentials (optional)

Variable	Maps to
POLYMARKET_API_KEY	API key
POLYMARKET_SECRET	HMAC secret
POLYMARKET_PASSPHRASE	Passphrase

If any are missing, the server derives credentials from your wallet (recommended).

Safety limits (optional)

Defaults in src/config.ts:

Variable	Purpose
MAX_ORDER_SIZE_USD	Cap per order
MAX_TOTAL_EXPOSURE_USD	Portfolio exposure limit
MAX_POSITION_SIZE_PER_MARKET	Per-market cap
MIN_LIQUIDITY_REQUIRED	Skip illiquid markets
MAX_SPREAD_TOLERANCE	Reject wide spreads
ENABLE_AUTONOMOUS_TRADING	Master switch for auto-execution
REQUIRE_CONFIRMATION_ABOVE_USD	Human-in-the-loop threshold
AUTO_CANCEL_ON_LARGE_SPREAD	Protect against book gaps

---

Available Tools (overview)

Market discovery — search, trending, categories, tags, paginated markets, slug lookup

Market analysis — order book depth, mid prices, volume, spread metrics

Trading — limit/market orders (token-aware), smart trade, cancel, balance allowance

Portfolio — positions, PnL, trade history via Data API

On-chain — approve_allowances, redeem_positions (needs POLYGON_RPC_URL)

Realtime — WebSocket subscriptions for market and user streams

Resources — polymarket://status, polymarket://config, polymarket://rate-limits

---

Architecture

src/
├── server.ts           # MCP stdio entry
├── clobBootstrap.ts    # Wallet → L2 credential derivation
├── config.ts           # Env + safety limits
├── tools/
│   ├── marketDiscovery.ts
│   ├── marketAnalysis.ts
│   ├── trading.ts
│   ├── portfolio.ts
│   └── realtime.ts
└── services/
    ├── approvals.ts
    └── redemption.ts

flowchart TB
    Client[Cursor / MCP Client] -->|stdio JSON-RPC| Server[MCP Server]
    Server --> Gamma[Gamma API]
    Server --> CLOB[CLOB API]
    Server --> Data[Data API]
    Server --> WS[WebSocket Feeds]
    Server --> Chain[Polygon RPC]

Loading

---

Operational Notes

• Stdio only — operator logs go to stderr; JSON-RPC uses stdout. Don't pipe debug output to stdout.
• WebSockets — connection failures are logged; HTTP discovery/analysis usually still works.
• Security — keys grant full account access. Use least privilege, rotate compromised keys immediately.

---

Development

npm run dev    # tsx watch
npm run build  # compile to dist/

---

License

MIT — see package metadata.