Polymarket Agent Mcp

io.github.demwickPublished by GitHub account demwickv1.7.0Updated Oct 24, 2026

Polymarket trading, market discovery, copy trading and backtesting — 48 MCP tools.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

A local MCP server that lets an assistant discover, analyze and trade Polymarket prediction markets, including copy trading, backtesting and portfolio risk.

What you can do
Search, browse and compare markets, events and top traders, including trending, featured and smart-money flow signals, with live prices and price history. Score markets and traders, check liquidity and holders, and get buy/sell/hold recommendations. Place, batch, limit and cancel orders, and switch from preview to live mode. Watch traders, run an automatic copy-trading monitor, rebalance the watchlist and backtest a trader's past trades. Review positions, balance, P&L, risk and optimization, set stop-loss and take-profit rules, and scan for arbitrage. Manage configuration, safety limits, trade history, watchlists and a dashboard.
When to use it
Useful when you want an assistant to research prediction markets, evaluate traders, simulate copy-trading strategies, or place real Polymarket orders from a local client. Preview mode makes it safe to explore without spending money.
Requirements
Runs locally over stdio, typically via npx or a global npm install (Node.js), or as a Docker image. Live trading needs COPY_MODE=live plus the Polymarket CLOB credentials POLY_API_KEY, POLY_API_PASSPHRASE and POLY_API_SECRET, the wallet key POLY_PRIVATE_KEY and POLY_FUNDER_ADDRESS. Outbound access to Polymarket APIs and a public price WebSocket; a local SQLite database file.
Before you install
Live mode places real orders and spends real USDC, capped by DAILY_BUDGET. POLY_PRIVATE_KEY is a Polygon wallet signing key; anyone with it can move funds, so keep it out of shared or public setups. The README warns that an HTTP instance has no per-user isolation and a public endpoint can drain the wallet; keep it local or behind auth. Preview mode is the default and uses no real money.

Installation

In SourceWeft

  1. Open Polymarket Agent Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Polymarket Agent MCP Server

[polymarket-agent-mcp MCP server]

[npm version] [CI] [GitHub last commit] [License: MIT] [Node.js] [TypeScript] [MCP SDK] [Tools] [Tests] [SafeSkill 97/100] [Socket Badge] [OpenSSF Scorecard] [OpenSSF Best Practices]

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

CategoryCountHighlights
Discovery9Search, trending, featured, events, related markets, smart money flow
Analysis8AI opportunity scoring, conviction rating, price history, market quality, top holders, comparison
Trading8Buy, sell, batch orders, limit orders, order management, safety limits
Copy Trading5Watch traders, auto-monitor, auto-rebalance, backtest
Portfolio10Positions, P&L, balance, risk assessment, SL/TP, optimization, market alerts
Utilities8Dashboard, config, trade history, watchlists, agent logging

Quick Start

npm Install

bash
npm install -g polymarket-agent-mcp

Docker

bash
docker compose up

Claude Code Config

Add to ~/.claude/settings.json:

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

ToolDescription
markets.searchSearch markets by keyword (bitcoin, election, UFC...)
traders.discoverFind top traders by PnL and volume
markets.discoverFind markets by end date and category
markets.trendingTop markets by 24h/7d/30d volume
markets.featuredMost liquid markets by category (politics, sports, crypto...)
wta.discoverWTA tennis markets with stink bid prices
flow.discoverSmart money signals — multiple top traders buying same market
markets.relatedFind markets related to a topic or market
markets.eventsBrowse all markets under an event

Analysis

ToolDescription
markets.analyzeAI-powered BUY/SELL/HOLD recommendation
traders.analyzeDetailed trader profile, win rate, P&L
traders.scoreConviction score (0-100) across 5 dimensions
markets.checkMarket quality — spread, depth, price range
markets.priceLive bid/ask/spread prices
markets.price_historyHistorical prices with sparkline (1h to 1m)
markets.holdersBiggest position holders in a market
markets.compareSide-by-side comparison of 2-5 markets

Trading

ToolDescription
orders.buyBuy shares on any market
orders.sellSell an open position
orders.batchExecute up to 10 orders at once
wta.bidPlace limit orders at discount
orders.cancelCancel all open orders
orders.listView pending limit orders
orders.statusCheck status of a specific order
config.go_liveSwitch from preview to live mode

Copy Trading

ToolDescription
watchlist.addAdd/remove traders from watchlist
monitor.startStart automatic copy trading loop
monitor.stopStop monitoring
watchlist.rebalanceRemove underperforming traders
traders.backtestSimulate copying a trader's past trades

Portfolio & Risk

ToolDescription
portfolio.balanceAccount balance, budget, and P&L
portfolio.getMulti-wallet overview with P&L per trader
positions.listOpen/closed positions
positions.closeManually close a position
positions.set_exit_rulesSet stop-loss and take-profit levels
positions.check_exitsCheck positions for resolution
portfolio.riskPortfolio risk scoring and warnings
portfolio.optimizeAI-powered optimization (conservative/balanced/aggressive)
markets.watchMarket watchlist with price alerts
markets.watch_priceLive WebSocket price subscriptions
markets.arbitrageFind YES+NO price discrepancies

Configuration

ToolDescription
config.setUpdate bot settings
config.safety_limitsMax order size, exposure cap, spread tolerance
dashboard.getTerminal-formatted dashboard
trades.historyTrade history with filters
watchlist.listShow watched wallets
agent.log_cycleLog agent cycle for dashboard
traders.positionsView 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:

ModeActivationUse case
stdio (default)npx polymarket-agent-mcpClaude Code, Cursor, local MCP clients
HTTP--http flag or PORT env varSelf-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

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

Endpoints

PathMethodDescription
/mcpPOSTMCP protocol endpoint (Streamable HTTP transport)
/healthGETHealth check — returns { status, version, db }
/.well-known/mcp/server-card.jsonGETMCP discovery card (tools, permissions, data handling)
/GETServer 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:

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

Or build it yourself from the included Dockerfile:

bash
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.

VariableRequiredDefaultDescription
COPY_MODENopreviewpreview (simulated) or live (real orders)
DAILY_BUDGETNo20Max daily spend in USDC
MIN_CONVICTIONNo3Min trade size to copy ($)
Wallet signing keyLive only-Locally signs CLOB order payloads, never persisted (see PERMISSIONS.md for exact env var name)
CLOB API credentialsLive 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.

CategoryScope
Network (outbound)3 Polymarket HTTPS APIs + 1 inbound-only WSS public price stream (ws-subscriptions-clob.polymarket.com)
FilesystemSingle SQLite database file + .env read at startup — nothing else
EnvironmentAPI credentials (live mode only, in memory only), budget config, mode selection
ProcessesNone — no child processes, no shell commands, no eval/Function
TelemetryNone — 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

bash
git clone https://github.com/demwick/polymarket-agent-mcp.gitcd polymarket-agent-mcpnpm installnpm run buildnpm test         # 200+ tests

License

MIT - see LICENSE

Source: README.md at commit ebe901c

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.7.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts