Polymarket MCP

Polymarket MCP Server

A Model Context Protocol (MCP) server for Polymarket prediction market data, built with Rust and the official MCP Rust SDK. 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 market details
Market Search: Search markets by keywords across questions, descriptions, and categories
Price Information: Get current yes/no prices for any market
MCP Resources: Auto-refreshing market data resources
MCP Prompts: AI-powered market analysis and arbitrage detection
Caching: Built-in caching with configurable TTL for performance
Configuration: Flexible configuration via environment variables or TOML files

Prerequisites

Rust 1.70+ (install via rustup)
Polymarket API credentials (optional for basic read-only access)

Installation

For Claude Desktop

Clone the repository:
git clone https://github.com/0x79de/polymarket-mcp cd polymarket-mcp
Build the release binary:
cargo build --release
Configure Claude Desktop:Edit your Claude Desktop configuration file at:
- 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": "/full/path/to/polymarket-mcp/target/release/polymarket-mcp", "env": { "RUST_LOG": "info" } } } }
Restart Claude Desktop to load the new MCP server.

Optional Configuration

Set up environment variables for enhanced functionality:

cp .env.example .env
# Edit .env with your API credentials (optional for basic usage)

Configuration

Environment Variables

Copy .env.example to .env and configure as needed:

# API Configuration
POLYMARKET_API_KEY=your_api_key_here
POLYMARKET_API_BASE_URL=https://gamma-api.polymarket.com

# Trading API Credentials (for advanced operations)
POLYMARKET_SECRET=your_secret_here
POLYMARKET_PASSPHRASE=your_passphrase_here

# Wallet Credentials (for blockchain interactions)
WALLET_PUBLIC_KEY=0x_your_public_key_here
WALLET_PRIVATE_KEY=your_private_key_here

# Server Settings
POLYMARKET_CACHE_ENABLED=true
POLYMARKET_CACHE_TTL=60
POLYMARKET_LOG_LEVEL=info

Configuration File

Alternatively, create a config.toml file:

[server]
name = "Polymarket MCP Server"
max_connections = 100
timeout_seconds = 30

[api]
base_url = "https://gamma-api.polymarket.com"
api_key = "your_api_key_here"
timeout_seconds = 30
max_retries = 3

[cache]
enabled = true
ttl_seconds = 60
max_entries = 1000

[logging]
level = "info"
format = "pretty"
enable_colors = true

Usage

Claude Desktop Integration

To use with Claude Desktop, configure your claude_desktop_config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/polymarket-mcp/target/release/polymarket-mcp",
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Configuration file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Building for Production

# Build release version for Claude Desktop
cargo build --release

# The binary will be at: target/release/polymarket-mcp

Standalone Server (Development)

# Run with default configuration (development mode)
cargo run

# Run with debug logging
RUST_LOG=debug cargo run

# Test the server manually (not recommended for production)
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":0}' | cargo run

MCP Tools

The server provides the following MCP tools:

`get_active_markets`

Fetch currently active prediction markets.

Parameters:

limit (optional): Maximum number of markets to return (default: 50)

Example:

{
  "tool": "get_active_markets",
  "arguments": {
    "limit": 10
  }
}

`get_market_details`

Get detailed information about a specific market.

Parameters:

market_id (required): The ID of the market

Example:

{
  "tool": "get_market_details",
  "arguments": {
    "market_id": "0x123..."
  }
}

`search_markets`

Search markets by keyword.

Parameters:

keyword (required): Search term
limit (optional): Maximum results (default: 20)

Example:

{
  "tool": "search_markets",
  "arguments": {
    "keyword": "election",
    "limit": 5
  }
}

`get_market_prices`

Get current yes/no prices for a market.

Parameters:

market_id (required): The ID of the market

`get_trending_markets`

Get markets with highest trading volume.

Parameters:

limit (optional): Maximum number of markets (default: 10)

MCP Resources

Auto-refreshing data resources:

markets:active - List of active markets
markets:trending - Trending markets by volume
market:{id} - Specific market details

MCP Prompts

AI-powered analysis prompts:

`analyze_market`

Comprehensive market analysis including sentiment, liquidity, and trading opportunities.

Arguments:

market_id (required): Market to analyze

`find_arbitrage`

Detect arbitrage opportunities across related markets.

Arguments:

keyword (required): Search term for related markets
limit (optional): Number of markets to analyze

`market_summary`

Overview of top prediction markets with trading recommendations.

Arguments:

category (optional): Filter by category
limit (optional): Number of markets to include

API Documentation

Market Object Structure

{
  "id": "0x123...",
  "slug": "market-slug",
  "question": "Will X happen by Y date?",
  "description": "Detailed market description",
  "active": true,
  "closed": false,
  "liquidity": 50000.0,
  "volume": 125000.0,
  "end_date": "2024-12-31T23:59:59Z",
  "outcomes": ["Yes", "No"],
  "outcome_prices": ["0.65", "0.35"],
  "category": "Politics"
}

Error Handling

The server implements comprehensive error handling:

Network Errors: Automatic retry with exponential backoff
Rate Limiting: Built-in rate limiting with configurable limits
Data Validation: All API responses are validated
Caching: Prevents redundant API calls

Development

Running Tests

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_market_client

Code Structure

src/
├── main.rs           # MCP server implementation
├── config.rs         # Configuration management
├── models.rs         # Data structures and types
└── polymarket_client.rs # Polymarket API client

Adding New Features

New Tools: Add methods to PolymarketMcpServer in main.rs
New Models: Define structures in models.rs
API Endpoints: Extend PolymarketClient in polymarket_client.rs
Configuration: Add options to Config in config.rs

Deployment

Docker

# Build Docker image
docker build -t polymarket-mcp .

# Run container
docker run -d \
  --name polymarket-mcp \
  -e POLYMARKET_API_KEY=your_key \
  -p 8080:8080 \
  polymarket-mcp

Systemd Service

Create /etc/systemd/system/polymarket-mcp.service:

[Unit]
Description=Polymarket MCP Server
After=network.target

[Service]
Type=simple
User=polymarket
ExecStart=/usr/local/bin/polymarket-mcp
Restart=always
RestartSec=10
Environment=RUST_LOG=info
EnvironmentFile=/etc/polymarket-mcp/.env

[Install]
WantedBy=multi-user.target

Troubleshooting

Common Issues

JSON Parsing Errors in Claude Desktop Logs

Error: Unexpected token '', " [2m2025-0"... is not valid JSON

Solution: This indicates logs are being written to stdout instead of stderr. The server has been configured to write all logs to stderr to avoid interfering with MCP JSON communication.

MCP Validation Errors

Error: Invalid input, Expected string, received null in id field

Solution: The server now properly handles JSON-RPC notifications (like notifications/initialized) by not responding to them, which is the correct behavior.

Server Connection Issues

Error: Server disconnected or Server transport closed unexpectedly

Troubleshooting steps:

Verify the binary path in your claude_desktop_config.json
Check that the binary exists: ls -la /path/to/target/release/polymarket-mcp
Test the binary manually: echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":0}' | /path/to/target/release/polymarket-mcp
Check logs in Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)

Build Issues

Error: cannot find function 'stdin' in module 'tokio::io'

Solution: Ensure tokio has the io-std feature enabled in Cargo.toml:

tokio = { version = "1.0", features = ["rt-multi-thread", "macros", "sync", "time", "signal", "io-std"] }

Debug Mode

Enable debug logging to see detailed MCP communication:

# In your claude_desktop_config.json
{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/polymarket-mcp/target/release/polymarket-mcp",
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}

Log Locations

Claude Desktop MCP Logs: ~/Library/Logs/Claude/mcp.log (macOS)
Claude Desktop Main Logs: ~/Library/Logs/Claude/main.log (macOS)
Server stderr output: Appears in Claude Desktop MCP logs

Monitoring

The server provides structured logging and can be monitored using:

Logs: JSON or pretty-printed logs with configurable levels (written to stderr)
Metrics: Built-in caching metrics and API call tracking
Health: Connection pooling and retry statistics
MCP Protocol: Full request/response logging in debug mode

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run tests: cargo test
Run lints: cargo clippy
Format code: cargo fmt
Submit a pull request

Security

API keys are handled securely and never logged
Private keys are optional and only used for trading operations
All HTTP connections use TLS
Input validation prevents injection attacks

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.1.1 (Current)

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 support
Improved: Proper JSON-RPC protocol compliance
Added: Comprehensive troubleshooting documentation
Added: Claude Desktop integration guide

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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

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

Polygon MCP Server
Dablclub
-
security
F
license
-
quality
A 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 -
68
TypeScript
Trading Simulator MCP Server
recallnet
-
security
F
license
-
quality
An 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 -
TypeScript
Scenario Word
HyunJuHwan
A
security
F
license
A
quality
A 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 -
TypeScript
Postman MCP Generator
punkpeye
A
security
F
license
A
quality
A 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

View all related MCP servers

Polymarket MCP Server

Features

Prerequisites

Installation

For Claude Desktop

Optional Configuration

Configuration

Environment Variables

Configuration File

Usage

Claude Desktop Integration

Building for Production

Standalone Server (Development)

MCP Tools

get_active_markets

get_market_details

search_markets

get_market_prices

get_trending_markets

MCP Resources

MCP Prompts

analyze_market

find_arbitrage

market_summary

API Documentation

Market Object Structure

Error Handling

Development

Running Tests

Code Structure

Adding New Features

Deployment

Docker

Systemd Service

Troubleshooting

Common Issues

JSON Parsing Errors in Claude Desktop Logs

MCP Validation Errors

Server Connection Issues

Build Issues

Debug Mode

Log Locations

Monitoring

Contributing

Security

License

Support

Changelog

v0.1.1 (Current)

v0.1.0

Related MCP Servers

Polygon MCP Server

Trading Simulator MCP Server

Scenario Word

Postman MCP Generator

New MCP Servers

MCP directory API

`get_active_markets`

`get_market_details`

`search_markets`

`get_market_prices`

`get_trending_markets`

`analyze_market`

`find_arbitrage`

`market_summary`