Polymarket Trader 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

One-Line Install

curl -fsSL https://raw.githubusercontent.com/demwick/polymarket-trader-mcp/main/install.sh | bash

npm Install

npm install -g polymarket-trader-mcp

Docker

docker compose up

Claude Code Config

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["polymarket-trader-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
search_markets	Search markets by keyword (bitcoin, election, UFC...)
discover_traders	Find top traders by PnL and volume
discover_markets	Find markets by end date and category
trending_markets	Top markets by 24h/7d/30d volume
featured_markets	Most liquid markets by category (politics, sports, crypto...)
discover_wta	WTA tennis markets with stink bid prices
discover_flow	Smart money signals — multiple top traders buying same market
find_related	Find markets related to a topic or market
get_market_events	Browse all markets under an event

Analysis

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

Trading

Tool	Description
buy	Buy shares on any market
sell	Sell an open position
batch_order	Execute up to 10 orders at once
place_stink_bid	Place limit orders at discount
cancel_orders	Cancel all open orders
get_open_orders	View pending limit orders
get_order_status	Check status of a specific order
go_live	Switch from preview to live mode

Copy Trading

Tool	Description
watch_wallet	Add/remove traders from watchlist
start_monitor	Start automatic copy trading loop
stop_monitor	Stop monitoring
rebalance	Remove underperforming traders
backtest_trader	Simulate copying a trader's past trades

Portfolio & Risk

Tool	Description
get_balance	Account balance, budget, and P&L
get_portfolio	Multi-wallet overview with P&L per trader
get_positions	Open/closed positions
close_position	Manually close a position
set_exit_rules	Set stop-loss and take-profit levels
check_exits	Check positions for resolution
assess_risk	Portfolio risk scoring and warnings
optimize_portfolio	AI-powered optimization (conservative/balanced/aggressive)
watch_market	Market watchlist with price alerts
detect_arbitrage	Find YES+NO price discrepancies

Configuration

Tool	Description
set_config	Update bot settings
set_safety_limits	Max order size, exposure cap, spread tolerance
get_dashboard	Terminal-formatted dashboard
get_trade_history	Trade history with filters
list_watchlist	Show watched wallets
log_cycle	Log agent cycle for dashboard
get_trader_positions	View a trader's open positions
discover_wta	WTA tennis market discovery

---

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

---

Configuration

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 ($)
POLY_PRIVATE_KEY	Live only	-	Polymarket wallet private key
POLY_API_KEY	Live only	-	CLOB API key
POLY_API_SECRET	Live only	-	CLOB API secret
POLY_API_PASSPHRASE	Live only	-	CLOB API passphrase

---

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

---

Development

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

---

License

MIT - see LICENSE