Content
# Polymarket MCP Server
Model Context Protocol (MCP) server for [**Polymarket**](https://polymarket.com): 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`](https://jsr.io) 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:
```bash
git clone https://github.com/japp-fi/polymarket-mcp-server
cd polymarket-mcp-server
```
```bash
npm install
npm run build
```
Development (TypeScript directly):
```bash
npm run dev
```
Production (compiled):
```bash
npm start
```
## Configuration
The server reads environment variables via [`dotenv`](https://www.npmjs.com/package/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
1. **`DEMO_MODE=true`** skips a funded wallet. Gamma/Data discovery (including **`get_positions`**) remains available unless a tool explicitly needs credentials.
2. **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](https://www.npmjs.com/package/@polymarket/clob-client)).
### 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`:
```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).
