Skip to main content
Glama

Polymarket MCP Server

by caiovicentino
GitHub
Python
MIT License
1
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

🤖 Polymarket MCP Server

Python 3.10+ License: MIT MCP Protocol Tests

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:

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

Developer Resources

Examples & Guides

💡 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 CONTRIBUTING.md 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

Get Support

📄 License

This project is licensed under the MIT License - see the LICENSE 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

📈 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

Built with ❤️ for autonomous AI trading on Polymarket

Ready to make Claude your personal prediction market trader! 🚀

⭐ Star this repo | 🐛 Report Bug | ✨ Request Feature

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables Claude to autonomously trade, analyze, and manage positions on Polymarket prediction markets with 45 comprehensive tools including market discovery, real-time monitoring, portfolio management, and AI-powered trading recommendations with enterprise-grade safety features.

  1. 👨‍💻 Created By
    1. ⭐ Key Features
      1. 🎯 45 Comprehensive Tools Across 5 Categories
      2. 🛡️ Enterprise-Grade Safety & Risk Management
      3. ⚙️ Production-Ready Infrastructure
    2. 🚀 Quick Start
      1. Installation
      2. Configuration
      3. Claude Desktop Integration
    3. 📖 Documentation
      1. Getting Started
      2. Developer Resources
      3. Examples & Guides
    4. 💡 Usage Examples
      1. Market Discovery
      2. Market Analysis
      3. Autonomous Trading
      4. Portfolio Management
      5. Real-time Monitoring
    5. 🧪 Testing
      1. 🛡️ Safety & Security
        1. ⚠️ Important Security Considerations
        2. Default Safety Limits
      2. 🤝 Contributing
        1. Quick Contribution Guide
      3. 📊 Project Stats
        1. 🌐 Community
          1. Join Our Communities
          2. Get Support
        2. 📄 License
          1. 🙏 Acknowledgments
            1. ⚠️ Disclaimer
              1. 🔗 Links
                1. 📈 Roadmap
                  1. Current Version (v0.1.0)
                  2. Planned Features

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/caiovicentino/polymarket-mcp-server'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server