caiovicentino/polymarket-mcp-server

🤖 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

🚀 Quick Start

Installation

# 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

# Copy the environment template
cp .env.example .env

# Edit with your Polygon wallet credentials
nano .env

Required credentials:

POLYGON_PRIVATE_KEY=your_private_key_without_0x_prefix
POLYGON_ADDRESS=0xYourPolygonAddress

Optional (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

• - Detailed installation and configuration instructions
• Quick Start Video - Video walkthrough (coming soon)

Developer Resources

• - Complete API documentation for all 45 tools
• - How to integrate with your agents
• - System design and architecture
• - Real-time data setup

Examples & Guides

• - Code examples for all tools
• - Example test implementations
• - Advanced analysis examples

💡 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 and suggest improvements"
"What's my P&L for the last 30 days?"
"Which are my best and worst performing markets?"
"Suggest portfolio optimizations for a conservative strategy"

Real-time Monitoring

"Subscribe to price changes for the government shutdown markets"
"Monitor my order status in real-time"
"Alert me when the Eagles vs Packers market moves more than 10%"
"Show me real-time orderbook updates for [token_id]"

🧪 Testing

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run specific test suite
pytest tests/test_trading_tools.py -v

# Run with coverage
pytest --cov=polymarket_mcp --cov-report=html

# Run market analysis demo
python demo_mcp_tools.py

Note: All tests use real Polymarket APIs - NO MOCKS!

🛡️ Safety & Security

⚠️ Important Security Considerations

• Private Key Protection: Never share or commit your private key
• Start Small: Begin with small amounts ($50-100) to test
• Understand Markets: Only trade in markets you understand
• Monitor Positions: Check your positions regularly
• Use Safety Limits: Configure appropriate limits for your risk tolerance
• Never Risk More: Than you can afford to lose

Default Safety Limits

MAX_ORDER_SIZE_USD=1000              # Maximum $1,000 per order
MAX_TOTAL_EXPOSURE_USD=5000          # Maximum $5,000 total exposure
MAX_POSITION_SIZE_PER_MARKET=2000    # Maximum $2,000 per market
MIN_LIQUIDITY_REQUIRED=10000         # Minimum $10,000 market liquidity
MAX_SPREAD_TOLERANCE=0.05            # Maximum 5% spread
REQUIRE_CONFIRMATION_ABOVE_USD=500   # Confirm orders over $500

These can be customized in your .env file or Claude Desktop config.

🤝 Contributing

Contributions are welcome! We appreciate your help making this project better.

Please read for details on:

• How to report bugs
• How to suggest features
• Code standards and guidelines
• Pull request process

Quick Contribution Guide

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📊 Project Stats

• Lines of Code: ~10,000+ (Python)
• Tools: 45 comprehensive tools
• Test Coverage: High (real API integration)
• Documentation: Comprehensive (multiple guides)
• Dependencies: Modern Python packages (MCP, httpx, websockets, eth-account)

🌐 Community

Join Our Communities

• 🌾 Yield Hacker - DeFi Innovation & Yield Farming
• 💰 Renda Cripto - Crypto Trading & Investments
• 🏗️ Cultura Builder - Builder Culture & Development

Get Support

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Telegram Communities: Get help from the community

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

This project was made possible by:

• Caio Vicentino - Creator and lead developer
• Yield Hacker Community - DeFi expertise and testing
• Renda Cripto Community - Trading insights and validation
• Cultura Builder Community - Builder culture and support
• Polymarket - Amazing prediction market platform
• Anthropic - Claude and the MCP protocol
• py-clob-client - Official Polymarket SDK

Special thanks to all contributors and community members who have helped improve this project!

⚠️ Disclaimer

This software is provided for educational and research purposes. Trading prediction markets involves financial risk.

Important Reminders:

• Cryptocurrency trading carries significant risk
• Only invest what you can afford to lose
• Past performance does not guarantee future results
• This is not financial advice
• Always do your own research (DYOR)
• Start with small amounts to learn the system
• Understand the markets you're trading
• Monitor your positions regularly

The authors and contributors are not responsible for any financial losses incurred through the use of this software.

🔗 Links

• GitHub Repository: github.com/caiovicentino/polymarket-mcp-server
• Polymarket: polymarket.com
• Polymarket Docs: docs.polymarket.com
• MCP Protocol: modelcontextprotocol.io
• Claude Code: claude.ai/code

📈 Roadmap

Current Version (v0.1.0)

• ✅ 45 comprehensive tools
• ✅ Real-time WebSocket monitoring
• ✅ Safety limits and risk management
• ✅ Complete test suite
• ✅ Comprehensive documentation

Planned Features

• CI/CD pipeline (GitHub Actions)
• Enhanced AI analysis tools
• Portfolio strategy templates
• Market alerts and notifications
• Performance analytics dashboard
• Multi-wallet support
• Advanced order types
• Historical backtesting