io.github.demwick/polymarket-agent-mcp MCP Server

Polymarket Agent MCP Server

Trade, analyze, and automate Polymarket prediction markets through AI.

The most comprehensive MCP server for Polymarket — 48 tools spanning direct trading, market discovery, smart money tracking, copy trading, backtesting, risk management, and portfolio optimization. Works with Claude Code, Cursor, or any MCP-compatible client.

---

Tool Overview

Category	Count	Highlights
Discovery	9	Search, trending, featured, events, related markets, smart money flow
Analysis	8	AI opportunity scoring, conviction rating, price history, market quality, top holders, comparison
Trading	8	Buy, sell, batch orders, limit orders, order management, safety limits
Copy Trading	5	Watch traders, auto-monitor, auto-rebalance, backtest
Portfolio	10	Positions, P&L, balance, risk assessment, SL/TP, optimization, market alerts
Utilities	8	Dashboard, config, trade history, watchlists, agent logging

---

Quick Start

npm Install

npm install -g polymarket-agent-mcp

Docker

docker compose up

Claude Code Config

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["polymarket-agent-mcp"]
    }
  }
}

---

Usage Examples

Just talk naturally to your AI assistant:

"What are the trending markets today?"

"Search for bitcoin prediction markets"

"Buy $5 on this market"

"Score this trader — should I copy them?"

"Backtest this trader with $10 per trade"

"Show smart money flow — what are the top traders buying?"

"Set stop-loss at 0.30 on my BTC position"

"Optimize my portfolio with a balanced strategy"

"Scan for arbitrage opportunities"

"Compare these two markets side by side"

---

All 48 Tools

Discovery

Tool	Description
markets.search	Search markets by keyword (bitcoin, election, UFC...)
traders.discover	Find top traders by PnL and volume
markets.discover	Find markets by end date and category
markets.trending	Top markets by 24h/7d/30d volume
markets.featured	Most liquid markets by category (politics, sports, crypto...)
wta.discover	WTA tennis markets with stink bid prices
flow.discover	Smart money signals — multiple top traders buying same market
markets.related	Find markets related to a topic or market
markets.events	Browse all markets under an event

Analysis

Tool	Description
markets.analyze	AI-powered BUY/SELL/HOLD recommendation
traders.analyze	Detailed trader profile, win rate, P&L
traders.score	Conviction score (0-100) across 5 dimensions
markets.check	Market quality — spread, depth, price range
markets.price	Live bid/ask/spread prices
markets.price_history	Historical prices with sparkline (1h to 1m)
markets.holders	Biggest position holders in a market
markets.compare	Side-by-side comparison of 2-5 markets

Trading

Tool	Description
orders.buy	Buy shares on any market
orders.sell	Sell an open position
orders.batch	Execute up to 10 orders at once
wta.bid	Place limit orders at discount
orders.cancel	Cancel all open orders
orders.list	View pending limit orders
orders.status	Check status of a specific order
config.go_live	Switch from preview to live mode

Copy Trading

Tool	Description
watchlist.add	Add/remove traders from watchlist
monitor.start	Start automatic copy trading loop
monitor.stop	Stop monitoring
watchlist.rebalance	Remove underperforming traders
traders.backtest	Simulate copying a trader's past trades

Portfolio & Risk

Tool	Description
portfolio.balance	Account balance, budget, and P&L
portfolio.get	Multi-wallet overview with P&L per trader
positions.list	Open/closed positions
positions.close	Manually close a position
positions.set_exit_rules	Set stop-loss and take-profit levels
positions.check_exits	Check positions for resolution
portfolio.risk	Portfolio risk scoring and warnings
portfolio.optimize	AI-powered optimization (conservative/balanced/aggressive)
markets.watch	Market watchlist with price alerts
markets.watch_price	Live WebSocket price subscriptions
markets.arbitrage	Find YES+NO price discrepancies

Configuration

Tool	Description
config.set	Update bot settings
config.safety_limits	Max order size, exposure cap, spread tolerance
dashboard.get	Terminal-formatted dashboard
trades.history	Trade history with filters
watchlist.list	Show watched wallets
agent.log_cycle	Log agent cycle for dashboard
traders.positions	View a trader's open positions

---

Architecture

Claude Code / Cursor / AI Client
        |
        | MCP Protocol (stdio)
        v
+------------------+
|  MCP Server      |  48 tools registered
|  (index.ts)      |
+--------+---------+
         |
    +----+----+
    |         |
 Tools    Services
    |         |
    v         v
+-------+ +------------+
| Zod   | | Backtester |
| Input | | Scorer     |
| Valid. | | SmartFlow  |
+-------+ | Filter     |
          | Tracker    |
          | Executor   |
          +-----+------+
                |
        +-------+-------+
        |       |       |
     Data    Gamma    CLOB
     API      API     API

---

HTTP Transport & Deployment

The server supports two transport modes:

Mode	Activation	Use case
stdio (default)	npx polymarket-agent-mcp	Claude Code, Cursor, local MCP clients
HTTP	--http flag or PORT env var	Self-hosted Docker, private VPS, single-user remote

Deployment model — read this first

This server is designed for single-tenant use. Each client runs its own instance with its own SQLite database (copytrader.db), watchlist, daily budget, trade history, and monitor loop. The stdio mode is the recommended path for most users — npx polymarket-agent-mcp or the Claude Code config above gives you a fully isolated, local-only instance.

⚠️ Do not expose an HTTP instance publicly. The server has no per-user isolation: watchlist, positions, budget, and the background monitor loop are shared across every client that connects. A public HTTP deployment is effectively a shared workspace, not a multi-tenant SaaS. If you enable live trading, a public endpoint can drain your Polymarket wallet from any caller. Always configure the HTTP bearer-token env var (see PERMISSIONS.md) and keep the endpoint behind a firewall, VPN, or auth proxy.

Starting in HTTP mode

# Flag
node dist/index.js --http

# Or set PORT (defaults to 3000)
PORT=8080 node dist/index.js

Endpoints

Path	Method	Description
/mcp	POST	MCP protocol endpoint (Streamable HTTP transport)
/health	GET	Health check — returns { status, version, db }
/.well-known/mcp/server-card.json	GET	MCP discovery card (tools, permissions, data handling)
/	GET	Server info with version and endpoint list

Authentication

The HTTP transport accepts an optional bearer token gated by an environment variable — the exact name is documented in PERMISSIONS.md. When set, clients must send Authorization: Bearer <token> on requests to /mcp; when unset the endpoint is open (suitable only for local or private networks).

Docker deployment

A prebuilt multi-arch image is published to GHCR on every release:

docker pull ghcr.io/demwick/polymarket-agent-mcp:1.7.0

Or build it yourself from the included Dockerfile:

docker build -t polymarket-mcp .
docker run -p 3000:3000 -v mcp-data:/app/data \
  -e DAILY_BUDGET=50 \
  polymarket-mcp
# To require bearer-token auth on /mcp, also pass the HTTP bearer env var
# listed in PERMISSIONS.md (e.g. `-e <VAR>=my-secret-key`).

DB_PATH (default /app/data/copytrader.db) controls where SQLite data is persisted — mount a volume to keep it across restarts.

---

Configuration

All secrets stay in memory for the lifetime of the process — they are never written to the database, logs, or disk, and are only transmitted to their designated Polymarket API endpoint over HTTPS. The complete authoritative env var list, with per-variable sensitivity and scope, lives in PERMISSIONS.md and SECURITY.md.

Variable	Required	Default	Description
COPY_MODE	No	preview	preview (simulated) or live (real orders)
DAILY_BUDGET	No	20	Max daily spend in USDC
MIN_CONVICTION	No	3	Min trade size to copy ($)
Wallet signing key	Live only	-	Locally signs CLOB order payloads, never persisted (see PERMISSIONS.md for exact env var name)
CLOB API credentials	Live only	-	API key / secret / passphrase — sent only to clob.polymarket.com (see PERMISSIONS.md for exact names)

---

Safety Features

• Configurable order size limits
• Total exposure caps
• Per-market position limits
• Minimum liquidity requirements
• Maximum spread tolerance
• Stop-loss / take-profit automation
• Preview mode (default) — no real money

---

Permissions & Capabilities

This package has a transparent, minimal footprint. Full disclosure: PERMISSIONS.md — machine-readable version in .well-known/mcp/server-card.json.

Category	Scope
Network (outbound)	3 Polymarket HTTPS APIs + 1 inbound-only WSS public price stream (ws-subscriptions-clob.polymarket.com)
Filesystem	Single SQLite database file + .env read at startup — nothing else
Environment	API credentials (live mode only, in memory only), budget config, mode selection
Processes	None — no child processes, no shell commands, no eval/Function
Telemetry	None — no analytics, no crash reports, no update checks, no third-party data flow

WebSocket scope: The WSS connection to Polymarket is inbound-only for public price updates. No wallet, credential, or user identity is transmitted — it carries the same public feed available to any browser client.

Secrets scope: Every secret environment variable is held in memory only, never logged, never persisted, and sent to exactly one host (see SECURITY.md).

---

Development

git clone https://github.com/demwick/polymarket-agent-mcp.git
cd polymarket-agent-mcp
npm install
npm run build
npm test         # 200+ tests

---

License

MIT - see LICENSE