polymarket-mcp-server

Implements the Model Context Protocol 1.0 specification to expose Polymarket trading capabilities as tools callable from Claude Desktop. The server.py module handles list_tools(), call_tool(), list_resources(), and read_resource() MCP handlers, translating natural language requests from Claude into structured API calls to Polymarket's CLOB and Gamma APIs. This enables seamless integration where Claude can discover available tools and execute trading operations with full context awareness.

Implements a two-stage authentication system where the PolymarketClient class manages both L1 wallet authentication (via EIP-712 message signing) and L2 API key credentials for Polygon-based Polymarket access. The system uses cryptographic signing to prove wallet ownership without exposing private keys, then exchanges signed proofs for API tokens that authorize subsequent CLOB and Gamma API calls. This architecture separates identity verification (wallet) from access control (API keys), enabling secure delegation of trading authority.

The project provides Dockerfile and Kubernetes manifests for containerized deployment of the MCP server. Docker packaging includes all dependencies and the Python runtime, enabling consistent execution across environments. Kubernetes manifests define Deployment, Service, and ConfigMap resources for orchestrated scaling and management. The deployment supports environment variable injection for configuration, persistent volume mounts for state, and health checks for availability monitoring.

The project includes a web dashboard (likely FastAPI-based) that provides real-time monitoring of server health, active connections, tool usage statistics, and configuration status. The dashboard exposes endpoints for viewing current portfolio state, recent trades, and system logs. This enables operators to monitor the MCP server without direct access to logs or metrics systems, and provides a visual interface for understanding server behavior.

The project includes a testing framework (likely pytest-based) with unit tests for individual components (config, safety limits, client authentication) and integration tests for end-to-end workflows (market discovery, order execution, portfolio tracking). Tests use mocking for external API calls to enable fast, deterministic execution without hitting live Polymarket endpoints. The CI/CD pipeline runs tests on every commit to ensure code quality and prevent regressions.

The project includes a CI/CD pipeline (likely GitHub Actions) that automatically runs tests, linting, and type checking on every commit and pull request. The pipeline builds Docker images, runs integration tests, and optionally deploys to staging or production environments. This ensures code quality standards are maintained and enables rapid, safe deployment of changes.

The SafetyLimits class implements a configurable validation pipeline that intercepts all trading tool calls before execution, checking against position limits, order size caps, daily loss thresholds, and market-specific restrictions. Each trading operation (buy, sell, cancel) passes through sequential validation stages: amount validation, wallet balance verification, portfolio exposure checks, and market liquidity assessment. Failed validations return detailed error messages to Claude without executing the trade, enabling safe autonomous trading with human-defined guardrails.

The market_discovery.py module provides 8 tools that query Polymarket's Gamma API to search, filter, and rank markets by keywords, categories, trending status, and liquidity metrics. Tools use full-text search on market titles and descriptions, category-based filtering (politics, sports, crypto, etc.), and sorting by volume, spread, or recency. Results are paginated and include market metadata (ID, question, current odds, liquidity, volume) enabling Claude to identify relevant prediction markets for analysis or trading.

The market_analysis.py module provides 10 tools that compute and expose market microstructure metrics including bid-ask spreads, order book depth, trading volume, price history, and AI-generated market recommendations. Tools fetch real-time data from Polymarket's CLOB API and WebSocket feeds, calculate derived metrics (spread percentage, liquidity depth at price levels), and format results for Claude interpretation. This enables Claude to assess market quality, identify arbitrage opportunities, and make informed trading decisions based on quantitative analysis.

The trading_tools.py module provides 12 tools for executing limit orders, market orders, and managing positions on Polymarket. Tools construct order objects with specified amount, price, and token type (YES/NO), submit them to the CLOB API, and return order IDs and execution status. The system supports order cancellation, position closing, and batch operations. All trading operations pass through the SafetyLimits validation pipeline before submission, ensuring compliance with configured risk limits.

The portfolio management tools aggregate user positions across all Polymarket markets, calculating total exposure, unrealized P&L, and portfolio composition. The system queries the CLOB API for all open positions associated with the authenticated wallet, computes metrics like position size, entry price, current market price, and profit/loss per position. Results are formatted as structured data that Claude can interpret to make portfolio-level decisions (rebalancing, risk reduction, profit-taking).

The real-time monitoring tools establish persistent WebSocket connections to Polymarket's price feeds, streaming live updates for bid, ask, and last-trade prices for subscribed markets. The system maintains in-memory state of price history and order book snapshots, enabling Claude to monitor market movements and trigger alerts or trading actions based on price thresholds. WebSocket data is buffered and deduplicated to handle network jitter and ensure data consistency.

The server supports a DEMO operational mode that exposes 25 read-only tools (all market discovery and market analysis tools) without requiring wallet authentication or API credentials. DEMO mode allows users to explore Polymarket, analyze markets, and understand the system's capabilities before committing to full authentication. This is implemented through conditional tool registration in the MCP server based on the operational mode configuration.

The config.py module implements a PolymarketConfig Pydantic model that loads configuration from environment variables, YAML files, or Python dicts. Configuration includes operational mode (DEMO/FULL), API credentials, wallet settings, safety limits, and deployment parameters. The load_config() function handles configuration precedence (environment > file > defaults) and validates all settings at load time using Pydantic's type checking and custom validators.