mcp protocol bridging for claude desktop market interaction
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.
Unique: Dual-layer MCP implementation that exposes both read-only market discovery/analysis tools (DEMO mode) and write-enabled trading tools (FULL mode) through the same protocol interface, with safety validation intercepting all write operations before they reach Polymarket APIs
vs alternatives: Unlike REST API wrappers or simple webhook integrations, this MCP server enables Claude to autonomously discover and reason about available trading tools while maintaining enterprise-grade safety guardrails at the protocol layer
dual-layer authentication with eip-712 wallet signing
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.
Unique: Separates wallet identity (L1) from API access (L2) using EIP-712 cryptographic proofs, allowing the server to authenticate without storing private keys and enabling fine-grained permission revocation at the API layer independent of wallet changes
vs alternatives: More secure than API-key-only systems because wallet ownership is cryptographically verified; more flexible than single-key systems because API credentials can be rotated without wallet re-authentication
docker and kubernetes deployment with containerized execution
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.
Unique: Provides both Docker and Kubernetes deployment options with health checks and configuration management, enabling the MCP server to be deployed as a scalable, managed service in enterprise environments
vs alternatives: More scalable than local deployment because Kubernetes enables horizontal scaling; more manageable than manual deployment because container orchestration handles restart and health monitoring
web dashboard for server monitoring and configuration
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.
Unique: Provides a web-based monitoring interface for the MCP server, enabling operators to observe server health and portfolio state without direct log access, complementing the Claude Desktop interface with a traditional web UI
vs alternatives: More accessible than log-based monitoring because it provides a visual interface; more comprehensive than simple health checks because it includes detailed metrics and portfolio state
comprehensive testing suite with unit and integration tests
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.
Unique: Includes both unit tests for individual components and integration tests for end-to-end workflows, with mocked external APIs to enable fast, deterministic testing without hitting live Polymarket endpoints
vs alternatives: More comprehensive than unit tests alone because integration tests verify end-to-end workflows; more practical than live API testing because mocked tests are fast and deterministic
ci/cd pipeline with automated testing and deployment
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.
Unique: Automates the entire pipeline from code commit through testing, Docker image building, and optional deployment, ensuring code quality and enabling rapid iteration without manual intervention
vs alternatives: More comprehensive than simple test automation because it includes linting, type checking, and deployment; more reliable than manual deployment because it enforces consistent processes
multi-stage safety validation pipeline for trading operations
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.
Unique: Implements a configurable, multi-stage validation pipeline that runs synchronously before any Polymarket API call, with detailed error messages that Claude can interpret to adjust trading strategy, rather than relying on post-execution monitoring or external circuit breakers
vs alternatives: More proactive than post-trade monitoring because it prevents invalid orders from reaching Polymarket; more flexible than hard-coded limits because all thresholds are configurable per deployment
market discovery and filtering with keyword and category search
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.
Unique: Exposes Polymarket's Gamma API search capabilities as Claude-callable tools with natural language query support, allowing Claude to discover markets through conversational queries like 'Show me trending crypto markets' rather than requiring structured API calls
vs alternatives: More discoverable than raw API access because Claude can reason about search results and iteratively refine queries; more flexible than static market lists because discovery is dynamic and responsive to user intent
+6 more capabilities