🤖 Polymarket MCP Server

Complete AI-Powered Trading Platform for Polymarket Prediction Markets

Enable Claude to autonomously trade, analyze, and manage positions on Polymarket with 45 comprehensive tools, real-time WebSocket monitoring, and enterprise-grade safety features.

---

👨‍💻 Created By

Caio Vicentino

Developed in collaboration with:

• 🌾 Yield Hacker - DeFi Innovation Community
• 💰 Renda Cripto - Crypto Trading Community
• 🏗️ Cultura Builder - Builder Culture Community

Powered by Claude Code from Anthropic

---

⭐ Key Features

🎯 45 Comprehensive Tools Across 5 Categories

<table> <tr> <td width="20%" align="center"><b>🔍<br/>Market Discovery</b><br/>8 tools</td> <td width="20%" align="center"><b>📊<br/>Market Analysis</b><br/>10 tools</td> <td width="20%" align="center"><b>💼<br/>Trading</b><br/>12 tools</td> <td width="20%" align="center"><b>📈<br/>Portfolio</b><br/>8 tools</td> <td width="20%" align="center"><b>⚡<br/>Real-time</b><br/>7 tools</td> </tr> </table>

🔍 Market Discovery (8 tools)

• Search and filter markets by keywords, categories, events
• Trending markets by volume (24h, 7d, 30d)
• Category-specific markets (Politics, Sports, Crypto)
• Markets closing soon alerts
• Featured and promoted markets
• Sports markets (NBA, NFL, etc.)
• Crypto prediction markets

📊 Market Analysis (10 tools)

• Real-time prices and spreads
• Complete orderbook depth analysis
• Liquidity and volume metrics
• Historical price data
• AI-powered opportunity analysis with BUY/SELL/HOLD recommendations
• Multi-market comparison
• Top holders analysis
• Risk assessment and scoring
• Spread calculation and monitoring

💼 Trading (12 tools)

• Limit orders (GTC, GTD, FOK, FAK)
• Market orders (immediate execution)
• Batch order submission
• AI-suggested pricing (aggressive/passive/mid strategies)
• Order status tracking and history
• Open orders management
• Single and bulk order cancellation
• Smart trade execution (natural language → automated strategy)
• Position rebalancing with slippage protection
• Order book integration

📈 Portfolio Management (8 tools)

• Real-time position tracking
• P&L calculation (realized/unrealized)
• Portfolio value aggregation
• Risk analysis (concentration, liquidity, diversification)
• Trade history with filters
• On-chain activity log
• Performance metrics
• AI-powered portfolio optimization (conservative/balanced/aggressive)

⚡ Real-time Monitoring (7 tools)

• Live price updates via WebSocket
• Orderbook depth streaming
• User order status notifications
• Trade execution alerts
• Market resolution notifications
• Subscription management
• System health monitoring
• Auto-reconnect with exponential backoff

🛡️ Enterprise-Grade Safety & Risk Management

• ✅ Order Size Limits - Configurable maximum per order
• ✅ Exposure Caps - Total portfolio exposure limits
• ✅ Position Limits - Per-market position caps
• ✅ Liquidity Validation - Minimum liquidity requirements
• ✅ Spread Tolerance - Maximum spread checks before execution
• ✅ Confirmation Flow - User confirmation for large orders
• ✅ Pre-trade Validation - Comprehensive safety checks

⚙️ Production-Ready Infrastructure

• ✅ L1 & L2 Authentication - Wallet (private key) + API key auth
• ✅ Advanced Rate Limiting - Token bucket algorithm respecting all Polymarket API limits
• ✅ EIP-712 Signing - Secure order signatures
• ✅ Auto-reconnect WebSockets - Resilient real-time connections
• ✅ Comprehensive Error Handling - User-friendly error messages
• ✅ No Mocks - Real Polymarket API integration throughout
• ✅ Full Test Coverage - Production-grade testing with real APIs

---

🌐 Web Dashboard

NEW: Manage and monitor your Polymarket MCP Server with a modern web interface!

# Start the web dashboard
polymarket-web

# Or use the quick start script
./start_web_dashboard.sh

Access at: http://localhost:8080

Dashboard Features

• Real-time Monitoring: Live MCP status, WebSocket connection, and statistics
• Configuration Management: Visual sliders for safety limits and trading controls
• Market Discovery: Search, filter, and browse markets with live updates
• Market Analysis: AI-powered analysis with recommendations and risk assessment
• System Monitoring: Performance charts, rate limits, and activity logs
• Dark Theme: Professional UI optimized for extended use

See WEB_DASHBOARD.md for complete documentation.

---

🚀 Quick Start

One-Command Installation (Recommended)

Try DEMO mode first (no wallet needed):

# macOS/Linux
curl -sSL https://raw.githubusercontent.com/caiovicentino/polymarket-mcp-server/main/quickstart.sh | bash

# Or clone and run locally
git clone https://github.com/caiovicentino/polymarket-mcp-server.git
cd polymarket-mcp-server
./quickstart.sh

Full installation (with trading):

# macOS/Linux
./install.sh

# Windows
install.bat

The automated installer will:

• ✓ Check Python version (3.10+)
• ✓ Create virtual environment
• ✓ Install all dependencies
• ✓ Configure environment
• ✓ Set up Claude Desktop integration
• ✓ Test the installation

Installation Options

| Method | Command | Best For | |--------|---------|----------| | Quick Start | ./quickstart.sh | First-time users, testing | | DEMO Mode | ./install.sh --demo | No wallet, read-only access | | Full Install | ./install.sh | Production trading setup | | Windows | install.bat | Windows users |

DEMO Mode vs Full Mode

DEMO Mode (No wallet required):

• ✅ Market discovery and search
• ✅ Real-time market analysis
• ✅ AI-powered insights
• ✅ Price monitoring
• ❌ Trading disabled (read-only)

Full Mode (Requires Polygon wallet):

• ✅ Everything in DEMO mode
• ✅ Place orders and execute trades
• ✅ Portfolio management
• ✅ Position tracking
• ✅ Real-time trade notifications

Manual Installation

If you prefer manual setup:

# Clone the repository
git clone https://github.com/caiovicentino/polymarket-mcp-server.git
cd polymarket-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

Configuration

Option 1: DEMO Mode (easiest)

cp .env.example .env
# Edit .env and set:
DEMO_MODE=true

Option 2: Full Trading Mode

cp .env.example .env
# Edit with your Polygon wallet credentials
nano .env

Required credentials (Full Mode):

POLYGON_PRIVATE_KEY=your_private_key_without_0x_prefix
POLYGON_ADDRESS=0xYourPolygonAddress

Recommended Safety Limits:

MAX_ORDER_SIZE_USD=1000
MAX_TOTAL_EXPOSURE_USD=5000
MAX_POSITION_SIZE_PER_MARKET=2000
MIN_LIQUIDITY_REQUIRED=10000
MAX_SPREAD_TOLERANCE=0.05
ENABLE_AUTONOMOUS_TRADING=false
REQUIRE_CONFIRMATION_ABOVE_USD=500

With ENABLE_AUTONOMOUS_TRADING=false (the default), every order is held and returned as confirmation_required until you re-issue it with confirm=true. Set it to true to let orders under REQUIRE_CONFIRMATION_ABOVE_USD go through without that step.

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "polymarket_mcp.server"],
      "cwd": "/path/to/polymarket-mcp-server",
      "env": {
        "POLYGON_PRIVATE_KEY": "your_private_key",
        "POLYGON_ADDRESS": "0xYourAddress"
      }
    }
  }
}

Restart Claude Desktop and you're ready to trade! 🎉

---

📖 Documentation

Getting Started

• Visual Installation Guide - Step-by-step with diagrams and screenshots
• FAQ - Frequently asked questions and troubleshooting
• Setup Guide - Detailed configuration instructions
• Demo Video Script - Video tutorial scripts

Developer Resources

• Tools Reference - Complete API documentation for all 45 tools
• Agent Integration Guide - How to integrate with your agents
• Trading Architecture - System design and architecture
• WebSocket Integration - Real-time data setup

Examples & Guides

• Usage Examples - Code examples for all tools
• Test Examples - Example test implementations
• Market Analysis Scripts - Advanced analysis examples

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    POLYMARKET MCP SERVER                    │
└─────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   Claude     │
    │   Desktop    │ (Natural language interface)
    └──────┬───────┘
           │ MCP Protocol
           ▼
    ┌──────────────────────────────────────────────┐
    │           MCP Server (Python)                │
    ├──────────────────────────────────────────────┤
    │  ┌────────────┐  ┌──────────────────────┐   │
    │  │  Mar