io.github.demwick/polymarket-agent-mcp
Polymarket trading, market discovery, copy trading and backtesting — 48 MCP tools.
Open source Open in the app JSON README (API)
About
Polymarket trading, market discovery, copy trading and backtesting — 48 MCP tools.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- demwick
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.7.0
- Stars
- 16
- Forks
- 4
- Open pull requests
- 12
- Last push
- 2026-09-03T01:33:55Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.demwick/polymarket-agent-mcp
README
# Polymarket Agent MCP Server
[](https://glama.ai/mcp/servers/demwick/polymarket-agent-mcp)
[](https://www.npmjs.com/package/polymarket-agent-mcp)
[](https://github.com/demwick/polymarket-agent-mcp/actions/workflows/ci.yml)
[](https://github.com/demwick/polymarket-agent-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.typescriptlang.org)
[](https://modelcontextprotocol.io)
[](#tool-overview)
[](tests/)
[](https://safeskill.dev/scan/demwick-polymarket-agent-mcp)
[](https://socket.dev/npm/package/polymarket-agent-mcp)
[](https://securityscorecards.dev/viewer/?uri=github.com/demwick/polymarket-agent-mcp)
[](https://www.bestpractices.dev/projects/12433)
**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
```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
| 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](PERMISSIONS.md)) and keep the endpoint behind a firewall, VPN, or auth proxy.
### Starting in HTTP mode
```bash
# 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](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](PERMISSIONS.md)** and **[SECURITY.md](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](PERMISSIONS.md)** — machine-readable version in [`.well-known/mcp/server-card.json`](.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](SECURITY.md#data-handling--secrets)).
---
## Development
```bash
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](LICENSE)