polymarket-mcp-server
π€ AI-Powered MCP Server for Polymarket - Enable Claude to trade prediction markets with 45 tools, real-time monitoring, and enterprise-grade safety features
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/caiovicentino--polymarket-mcp-server)HTML
<a href="/listings/caiovicentino--polymarket-mcp-server"><img src="/api/listings/caiovicentino--polymarket-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
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! π
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 589 lines Β· 1 finding marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # π€ Polymarket MCP Server
- [](https://www.python.org/downloads/)
- [](LICENSE)
- [](https://modelcontextprotocol.io)
- [](#testing)
- [](https://agentseal.org/mcp/polymarket-mcp)
- **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](https://github.com/caiovicentino)**
- Developed in collaboration with:
- - πΎ **[Yield Hacker](https://opensea.io/collection/yield-hacker-pass-yhp)** - DeFi Innovation Community
- - π° **[Renda Cripto](https://rendacripto.com.br/)** - Crypto Trading Community
- - ποΈ **[Cultura Builder](https://culturabuilder.com/)** - Builder Culture Community
- Powered by **[Claude Code](https://claude.ai/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!
- ```bash
- # 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](WEB_DASHBOARD.md) for complete documentation.
- ---
- ## π Quick Start
- ### One-Command Installation (Recommended)
- **Try DEMO mode first** (no wallet needed):
- ```bash
- # macOS/Linux
- curl -sSL https://raw.githubusercontent.com/caiovicentino/polymarket-mcp-server/main/quickstart.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 150 on GitHub
- # 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):
- ```bash
- # 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:
- ```bash
- # 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)
- ```bash
- cp .env.example .env
- # Edit .env and set:
- DEMO_MODE=true
- ```
- **Option 2: Full Trading Mode**
- ```bash
- cp .env.example .env
- # Edit with your Polygon wallet credentials
- nano .env
- ```
- **Required credentials (Full Mode):**
- ```env
- POLYGON_PRIVATE_KEY=your_private_key_without_0x_prefix
- POLYGON_ADDRESS=0xYourPolygonAddress
- ```
- **Recommended Safety Limits:**
- ```env
- 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`
- ```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](VISUAL_INSTALL_GUIDE.md)** - Step-by-step with diagrams and screenshots
- - **[FAQ](FAQ.md)** - Frequently asked questions and troubleshooting
- - **[Setup Guide](SETUP_GUIDE.md)** - Detailed configuration instructions
- - **[Demo Video Script](DEMO_VIDEO_SCRIPT.md)** - Video tutorial scripts
- ### Developer Resources
- - **[Tools Reference](TOOLS_REFERENCE.md)** - Complete API documentation for all 45 tools
- - **[Agent Integration Guide](AGENT_INTEGRATION_GUIDE.md)** - How to integrate with your agents
- - **[Trading Architecture](TRADING_ARCHITECTURE.md)** - System design and architecture
- - **[WebSocket Integration](WEBSOCKET_INTEGRATION.md)** - Real-time data setup
- ### Examples & Guides
- - **[Usage Examples](USAGE_EXAMPLES.py)** - Code examples for all tools
- - **[Test Examples](TEST_EXAMPLES.py)** - Example test implementations
- - **[Market Analysis Scripts](analyze_top_markets.py)** - 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 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
- ```bash
- # 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
- ```env
- 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
- ENABLE_AUTONOMOUS_TRADING=false # Every order needs confirm=true
- REQUIRE_CONFIRMATION_ABOVE_USD=500 # When autonomous: confirm orders over $500
- ```
- These can be customized in your `.env` file or Claude Desktop config.
- ### Choosing the Outcome
- Order tools take an `outcome` argument (`"Yes"`, `"No"`, or a label like
- `"Lakers"`). On a Yes/No market it defaults to `Yes`. Sports and multi-outcome
- markets have no Yes/No side, so the outcome must be given explicitly β the tool
- refuses the order and lists the available outcomes rather than guessing a side.
- ---
- ## π€ Contributing
- Contributions are welcome! We appreciate your help making this project better.
- Please read [CONTRIBUTING.md](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
- - πΎ **[Yield Hacker](https://opensea.io/collection/yield-hacker-pass-yhp)** - DeFi Innovation & Yield Farming
- - π° **[Renda Cripto](https://rendacripto.com.br/)** - Crypto Trading & Investments
- - ποΈ **[Cultura Builder](https://culturabuilder.com/)** - Builder Culture & Development
- ### Featured In
- - **[Awesome Agent Trading](https://github.com/laplace0x/awesome-agent-trading)** - Curated directory of AI trading agents, MCP servers, and prediction market tools
- ### Get Support
- - **GitHub Issues**: [Report bugs or request features](https://github.com/caiovicentino/polymarket-mcp-server/issues)
- - **GitHub Discussions**: [Ask questions and share ideas](https://github.com/caiovicentino/polymarket-mcp-server/discussions)
- - **Telegram Communities**: Get help from the community
- ---
- ## π License
- This project is licensed under the MIT License - see the [LICENSE](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](https://polymarket.com)** - Amazing prediction market platform
- - **[Anthropic](https://anthropic.com)** - Claude and the MCP protocol
- - **[py-clob-client](https://github.com/Polymarket/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](https://github.com/caiovicentino/polymarket-mcp-server)
- - **Polymarket**: [polymarket.com](https://polymarket.com)
- - **Polymarket Docs**: [docs.polymarket.com](https://docs.polymarket.com)
- - **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- - **Claude Code**: [claude.ai/code](https://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
- ---
- ## π Contributors
- Thanks to everyone who has contributed to this project!
- [](https://github.com/caiovicentino/polymarket-mcp-server/graphs/contributors)
- ---
- <div align="center">
- **Built with β€οΈ for autonomous AI trading on Polymarket**
- *Ready to make Claude your personal prediction market trader!* π
- [β Star this repo](https://github.com/caiovicentino/polymarket-mcp-server) | [π Report Bug](https://github.com/caiovicentino/polymarket-mcp-server/issues) | [β¨ Request Feature](https://github.com/caiovicentino/polymarket-mcp-server/issues)
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.