🤖 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

🔍 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=true
REQUIRE_CONFIRMATION_ABOVE_USD=500

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)                │
    ├──────────────────────────────────────────────┤
    │  ┌────────────┐  ┌──────────────────────┐   │
    │  │  Market    │  │  Trading             │   │
    │  │  Discovery │  │  Engine              │   │
    │  │  (8 tools) │  │  (12 tools)          │   │
    │  └────────────┘  └──────────────────────┘   │
    │                                              │
    │  ┌────────────┐  ┌──────────────────────┐   │
    │  │  Market    │  │  Portfolio           │   │
    │  │  Analysis  │  │  Manager             │   │
    │  │  (10 tools)│  │  (8 tools)           │   │
    │  └────────────┘  └──────────────────────┘   │
    │                                              │
    │  ┌──────────────────────────────────────┐   │
    │  │  Real-time WebSocket (7 tools)       │   │
    │  └──────────────────────────────────────┘   │
    └──────────────┬───────────────────────────────┘
                   │
                   ▼
    ┌──────────────────────────────────────────────┐
    │         Polymarket Infrastructure            │
    ├──────────────────────────────────────────────┤
    │  • CLOB API (Order placement & management)   │
    │  • Gamma API (Market data & analytics)       │
    │  • WebSocket (Real-time price feeds)         │
    │  • Polygon Chain (Settlement & execution)    │
    └──────────────────────────────────────────────┘

---

💡 Usage Examples

Market Discovery

Ask Claude:

"Show me the top 10 trending markets on Polymarket in the last 24 hours"
"Find all crypto markets about Bitcoin"
"What sports markets are closing in the next 12 hours?"
"Search for markets about Trump"

Market Analysis

"Analyze the trading opportunity for the government shutdown market"
"Compare these three markets and tell me which has the best risk/reward"
"What's the current spread on the Eagles vs Packers market?"
"Show me the orderbook depth for token ID xyz"

Autonomous Trading

"Buy $100 of YES tokens in [market_id] at $0.65"
"Place a limit order: sell 200 NO at $0.40 in [market]"
"Execute a smart trade: buy YES up to $500 in [market] using best strategy"
"Cancel all my open orders in the government shutdown market"
"Rebalance my position in [market] to $1000 with max 2% slippage"

Portfolio Management

"Show me all my current positions"
"What's my total portfolio value?"
"Analyze my portfolio risk a