Polymarket MCP Server

MCP (Model Context Protocol) server that exposes Polymarket prediction markets via CLI wrapper.

Enables AI agents to discover markets, check prices, and place trades programmatically.

---

Features

Read-Only Tools (No Wallet Required)

• markets_search — Search markets by keyword
• markets_get — Get specific market details
• markets_list — List markets with filters (active, volume, etc.)
• clob_price — Get current price for token ID
• clob_midpoint — Get midpoint price
• clob_book — Get order book depth
• price_history — Historical prices (1m, 1h, 1d, etc.)

Authenticated Tools (Requires Wallet)

• create_order — Place limit order (buy/sell at specified price)
• market_order — Place market order (buy/sell at current price)
• cancel_order — Cancel existing order
• positions — Get portfolio positions
• balance — Get wallet balance (USDC/conditional tokens)

---

Installation

Prerequisites

1. Install Polymarket CLI:

   brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli
   brew install polymarket
   

2. Verify CLI works:

   polymarket markets list --limit 3
   

Install MCP Server

cd polymarket-mcp
npm install
npm run build

---

Configuration

Environment Variables

Create .env file (see .env.example):

# Required for authenticated operations (trading)
POLYMARKET_PRIVATE_KEY=0x...

# Optional
CHAIN_ID=137                # Polygon mainnet
SIGNATURE_TYPE=proxy        # proxy | eoa | gnosis-safe
POLYGON_RPC_URL=https://polygon-rpc.com

MCP Client Config

Add to your MCP client config (e.g., Claude Desktop, mcporter, Polygent):

{
  "mcpServers": {
    "polymarket": {
      "command": "node",
      "args": ["/path/to/polymarket-mcp/dist/index.js"],
      "env": {
        "POLYMARKET_PRIVATE_KEY": "0x...",
        "CHAIN_ID": "137",
        "SIGNATURE_TYPE": "proxy"
      }
    }
  }
}

---

Usage Examples

Browse Markets

// Search for Bitcoin markets
markets_search({ query: "bitcoin", limit: 5 })

// Get specific market
markets_get({ market_id: "will-btc-hit-100k" })

// List active markets sorted by volume
markets_list({ active: true, order: "volume_num", limit: 10 })

Check Prices

// Get buy price
clob_price({ token_id: "0xABC...", side: "buy" })

// Get midpoint (average of bid/ask)
clob_midpoint({ token_id: "0xABC..." })

// Get full order book
clob_book({ token_id: "0xABC..." })

// Get price history
price_history({ token_id: "0xABC...", interval: "1d", fidelity: 30 })

Trade (Authenticated)

// Place limit order: buy 10 shares at $0.50
create_order({
  token_id: "0xABC...",
  side: "buy",
  price: 0.50,
  size: 10
})

// Place market order: buy $5 worth at current price
market_order({
  token_id: "0xABC...",
  side: "buy",
  amount: 5
})

// Cancel order
cancel_order({ order_id: "0xORDER..." })

// Check positions
positions({ wallet_address: "0xYOUR_WALLET..." })

// Check balance
balance({ asset_type: "collateral" })

---

Security

Wallet Key Management

• Never log private keys — Keys are only used for CLI signing
• Environment variables only — Keys never hardcoded
• No key exposure in responses — MCP responses don't include keys

Input Validation

• All inputs validated with Zod before CLI execution
• Token IDs must match hex pattern (0x[0-9a-fA-F]+)
• Wallet addresses validated (0x[0-9a-fA-F]{40})
• Price bounds enforced (0.01 to 0.99)
• Positive size/amount validation

Rate Limiting

• CLI timeout: 30 seconds per command
• Buffer limit: 10MB max response size
• Respects Polymarket API rate limits (60 req/min)

Command Injection Protection

• No shell interpolation of user input
• Pre-validated arguments passed as array
• Uses child_process.exec with timeout + buffer limits

---

Testing

Manual Test (MCP Inspector)

npx @modelcontextprotocol/inspector node dist/index.js

Test Read-Only Tools

# List markets
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"markets_search","arguments":{"query":"bitcoin","limit":3}}}' | node dist/index.js

Test Authenticated Tools

Requires .env with POLYMARKET_PRIVATE_KEY:

# Check balance
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"balance","arguments":{"asset_type":"collateral"}}}' | node dist/index.js

---

Integration with Polygent

See INTEGRATION.md for detailed integration guide.

Quick start:

1. Install MCP server on Polygent VPS
2. Configure mcporter with server path + env vars
3. Update Polygent agents to call MCP tools
4. Add health checks for MCP server status

---

Troubleshooting

"Wallet not configured" error

• Set POLYMARKET_PRIVATE_KEY in .env or MCP client config
• Verify key format: 0x + 64 hex characters

"Command not found: polymarket"

• Install Polymarket CLI: brew install polymarket
• Verify: which polymarket

"Failed to parse CLI output"

• Check CLI version: polymarket --version
• Ensure JSON output mode works: polymarket -o json markets list --limit 1

Rate limit errors (429)

• Respect 60 req/min limit
• Add exponential backoff in agent logic
• Use batch endpoints where available

---

Architecture

polymarket-mcp/
├── src/
│   ├── index.ts           # MCP server (tool definitions)
│   └── lib/
│       ├── env.ts         # Environment validation (Zod)
│       ├── cli.ts         # CLI wrapper functions
│       └── types.ts       # TypeScript types
├── dist/                  # Compiled output
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Design:

• No database — Pure CLI wrapper
• Fail-fast validation — Env vars checked at startup
• Structured errors — Always return error objects, never throw
• Type-safe — Full TypeScript + Zod validation

---

Related Projects

• Polymarket CLI: https://github.com/Polymarket/polymarket-cli
• MCP Specification: https://modelcontextprotocol.io
• Polygent: https://polygent.market

---

License

MIT