Supports configuration via environment variables loaded from .env files for API credentials, trading configurations, and server settings.
Built using the Rust programming language and the official MCP Rust SDK for performance, safety, and reliability.
Allows configuration via TOML files for server settings, API connections, caching, and logging preferences.
Polymarket MCP Server
A high-performance Model Context Protocol (MCP) server for Polymarket prediction market data, built with Rust. This server provides real-time market data, prices, and betting information from Polymarket through MCP tools, resources, and prompts.
Features
🔄 Real-time Market Data: Fetch active markets, trending markets, and detailed market information
🔍 Advanced Search: Search markets by keywords across questions, descriptions, and categories
💰 Price Information: Get current yes/no prices and market statistics
📊 MCP Resources: Auto-refreshing market data resources with intelligent caching
🤖 AI-Powered Prompts: Market analysis, arbitrage detection, and trading insights
⚡ High Performance: Built-in caching, connection pooling, and optimized for speed
🔧 Flexible Configuration: Environment variables, TOML files, or defaults
🏗️ Production Ready: Zero compilation warnings, comprehensive error handling, full test coverage
Quick Start
Prerequisites
Rust 1.70+ - Install via rustup
Claude Desktop - Download from Claude.ai
Internet Connection - For Polymarket API access (no API key required)
Installation
Option 1: Download Pre-built Binary (Recommended)
Download the latest release for your platform:
Visit Releases
Download the appropriate binary for your OS
Configure Claude Desktop:
Edit your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
Add the Polymarket MCP server:
{ "mcpServers": { "polymarket": { "command": "/path/to/polymarket-mcp/target/release/polymarket-mcp", "env": { "RUST_LOG": "info" } } } }Restart Claude Desktop to load the new MCP server.
Option 2: Build from Source
Clone and build:
git clone https://github.com/0x79de/polymarket-mcp cd polymarket-mcp cargo build --releaseUse the binary at
target/release/polymarket-mcp
in your Claude Desktop configuration.
Option 3: Docker Deployment
Build Docker image:
docker build -t polymarket-mcp:latest .Configure Claude Desktop for Docker:
Edit your Claude Desktop configuration file:
# macOS vim ~/Library/Application\ Support/Claude/claude_desktop_config.json # Windows notepad %APPDATA%\Claude\claude_desktop_config.json # Linux nano ~/.config/Claude/claude_desktop_config.jsonAdd the Docker configuration:
{ "mcpServers": { "polymarket": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "RUST_LOG=info", "-e", "POLYMARKET_CACHE_TTL=300", "polymarket-mcp:latest" ], "env": { "RUST_LOG": "info" } } } }Restart Claude Desktop to load the new MCP server.
Option 4: Install via Cargo
The binary will be installed to ~/.cargo/bin/polymarket-mcp
.
Configuration (Optional)
The server works out-of-the-box with sensible defaults. No configuration is required for basic usage.
Environment Variables
Create a .env
file for custom configuration:
Configuration File
Alternatively, copy config.toml.example
to config.toml
and customize:
Configuration Priority
Configuration is loaded in this order (highest to lowest priority):
Environment variables (e.g.,
POLYMARKET_LOG_LEVEL=debug
)Configuration file (
config.toml
,polymarket-mcp.toml
, etc.)Built-in defaults (production-ready settings)
Usage
Claude Desktop Integration
After installing and configuring the MCP server, you can interact with Polymarket data directly through Claude Desktop. Try these example prompts:
Example Usage Flow
Ask Claude: "Show me active prediction markets about AI"
Claude uses:
search_markets
tool with keyword "AI"You get: List of AI-related markets with prices and details
Follow up: "Analyze the most liquid AI market"
Claude uses:
analyze_market
prompt for deep insights
Development & Testing
MCP Protocol Implementation
This server implements the full MCP specification with 5 tools, 3 resources, and 3 prompts.
🔧 MCP Tools
Tool | Description | Parameters |
| Fetch currently active prediction markets |
(optional, default: 50) |
| Get detailed information about a specific market |
(required) |
| Search markets by keyword in questions/descriptions |
(required),
(optional, default: 20) |
| Get current yes/no prices for a market |
(required) |
| Get markets with highest trading volume |
(optional, default: 10) |
📊 MCP Resources
Auto-refreshing data resources that Claude can access:
Resource | Description | Refresh Rate |
| List of currently active markets | Every 5 minutes |
| Markets sorted by trading volume | Every 5 minutes |
| Specific market details by ID | Every 5 minutes |
🤖 MCP Prompts
AI-powered analysis prompts for intelligent market insights:
Prompt | Description | Arguments |
| Comprehensive market analysis with trading insights |
(required) |
| Detect arbitrage opportunities across related markets |
(required),
(optional, default: 10) |
| Overview of top markets with recommendations |
(optional),
(optional, default: 5) |
API Documentation
Market Object Structure
Error Handling
The server implements robust error handling:
Network Errors: Automatic retry with exponential backoff and jitter
Rate Limiting: Automatic delays for rate-limited requests
Data Validation: All API responses are validated and parsed safely
Caching: Prevents redundant API calls and improves performance
Development
Code Structure
Key Features of the Implementation
Clean Architecture: Minimal dependencies, focused functionality
Type Safety: Comprehensive Rust type system usage
Performance: Efficient caching and HTTP connection pooling
Reliability: Robust error handling and retry logic
MCP Compliance: Full implementation of MCP protocol specification
Quality Assurance
This project maintains high code quality standards:
Current Status:
✅ Zero compilation warnings
✅ All tests passing (11/11)
✅ Clean clippy lints
✅ 100% API coverage
Dependencies
The project uses minimal, focused dependencies:
Deployment
Docker Deployment
Production Docker Compose
Create docker-compose.yml
:
Systemd Service (Linux)
For Linux servers, create /etc/systemd/system/polymarket-mcp.service
:
Troubleshooting
Common Issues
Server Won't Start
Check these steps:
Verify binary path:
ls -la /path/to/target/release/polymarket-mcp
Test binary:
./target/release/polymarket-mcp --help
Check configuration:
RUST_LOG=debug cargo run
MCP Connection Issues
Troubleshooting:
Verify
claude_desktop_config.json
syntax is valid JSONCheck absolute path to binary in configuration
Restart Claude Desktop after configuration changes
Check Claude Desktop logs:
~/Library/Logs/Claude/mcp.log
(macOS)
API Errors
Common solutions:
Verify internet connectivity
Check API endpoint availability
Ensure no rate limiting (automatic handling built-in)
Review error logs with
RUST_LOG=debug
Debug Mode
Enable debug logging for detailed output:
Log Locations
Claude Desktop MCP Logs:
~/Library/Logs/Claude/mcp.log
(macOS)Claude Desktop Main Logs:
~/Library/Logs/Claude/main.log
(macOS)Server Output: All logs go to stderr, visible in Claude Desktop MCP logs
Performance
The server is optimized for performance:
Caching: Intelligent caching with configurable TTL
Connection Pooling: Reuses HTTP connections efficiently
Minimal Allocations: Efficient memory usage patterns
Async Processing: Non-blocking I/O throughout
Fast JSON: Optimized serialization/deserialization
Security
API keys are handled securely and never logged
All HTTP connections use TLS encryption
Input validation prevents injection attacks
No sensitive data is cached or logged
Minimal attack surface with focused dependencies
Contributing
We welcome contributions! Please follow these steps:
Fork the repository and create a feature branch
Make your changes with proper tests
Ensure quality standards:
cargo test # All tests must pass cargo clippy --all-targets --all-features -- -D warnings -A clippy::pedantic cargo fmt --check # Code must be formatted cargo check # No compilation warningsSubmit a pull request with conventional commit messages
Development Guidelines
Zero warnings policy: All code must compile without warnings
Test coverage: New features must include tests
Documentation: Update README for user-facing changes
Performance: Consider caching and efficiency
Security: No API keys in code, secure error handling
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
Issues: GitHub Issues
Documentation: MCP Specification
Polymarket API: Official Documentation
Changelog
v0.3.0 (Current)
🎯 Zero Warnings: Completely clean compilation with zero warnings
📊 Full MCP Implementation: 5 tools, 3 resources, 3 prompts
⚡ Performance Optimized: Connection pooling, intelligent caching, retry logic
🧪 Comprehensive Testing: 11 tests covering all functionality
📚 Enhanced Documentation: Updated README with examples and installation options
🔧 Production Ready: Robust error handling and configuration management
v0.1.1
Fixed: JSON parsing errors in Claude Desktop by redirecting logs to stderr
Fixed: MCP validation errors with notification handling
Fixed: Added
io-std
feature to tokio for stdin/stdout supportImproved: Proper JSON-RPC protocol compliance
Added: Comprehensive troubleshooting documentation
v0.1.0
Initial release with core MCP functionality
Support for market data fetching and searching
MCP resources and prompts implementation
Comprehensive configuration system
Built-in caching and error handling
Archive
This server cannot be installed
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.
A Model Context Protocol (MCP) server for Polymarket prediction markets, providing real-time market data, prices, and AI-powered analysis tools for Claude Desktop integration.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol (MCP) server that provides onchain tools for Claude AI, allowing it to interact with the Polygon PoS blockchain to call contract functions, manage ERC20 tokens, and check gas prices.Last updated -106
- AsecurityFlicenseAqualityAn MCP server that enables AI models like Claude to interact with the Trading Simulator API for checking balances, viewing prices, and executing trades with automatic chain detection.Last updated -15
- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server that allows Claude AI to interact with custom tools, enabling extension of Claude's capabilities through the MCP framework.Last updated -
- AsecurityFlicenseAqualityA Model Context Provider (MCP) server that exposes your automated API tools to MCP-compatible clients like Claude Desktop, allowing you to interact with APIs using natural language.Last updated -3