# 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:**
   ```bash
   brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli
   brew install polymarket
   ```

2. **Verify CLI works:**
   ```bash
   polymarket markets list --limit 3
   ```

### Install MCP Server

```bash
cd polymarket-mcp
npm install
npm run build
```

---

## Configuration

### Environment Variables

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

```bash
# 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):

```json
{
  "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

```typescript
// 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

```typescript
// 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)

```typescript
// 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)

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

### Test Read-Only Tools

```bash
# 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`:

```bash
# 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