polymarket-mcp

# Polymarket MCP Server Access Polymarket's prediction markets through agents like Claude Code or chatbots like ChatGPT. Hit 50k users in March 2026 <img width="1117" height="292" alt="image" src="https://github.com/user-attachments/assets/87bc49ce-edc3-4625-8af6-59130dc9fa05" /> <img width="1572" height="1754" alt="image" src="https://github.com/user-attachments/assets/271d4d9d-2fc7-44d4-b591-65f051d35b98" /> ## Features - **Market Discovery**: Search and filter prediction markets by tags, volume, liquidity, and more - **Event Analysis**: Access grouped markets and event clusters (e.g., elections, sports, economics) - **Trading Data**: View recent trades, analyze trading patterns and market sentiment - **Comprehensive Analysis**: Get AI-friendly insights with probabilities, volume, liquidity, and market health - **Public Access**: No authentication required - uses Polymarket's public APIs - **Real-time Data**: Access to both Gamma Markets API and Data API Use this to build market analysis tools, trading assistants, event outcome analyzers, and educational platforms that make prediction markets more accessible. ## Tools Included ### 1. `search_markets` Search Polymarket prediction markets with advanced filtering: - Filter by tags, volume, liquidity, closed status - Order by any field (volume, liquidity, etc.) - Pagination support **Example**: "Show me the top 5 most active political markets" ### 2. `get_market` Get detailed information about a specific market by slug: - Current probabilities for all outcomes - Volume (24h and total), liquidity - Market status and end date - Full market metadata **Example**: "Analyze the market for trump-popular-vote-2024" ### 3. `search_events` Search Polymarket events (collections of related markets): - Filter by tags, featured status, closed status - See all markets within an event - Event-level volume and liquidity **Example**: "Find all active sports events" ### 4. `get_event` Get detailed information about a specific event: - All markets within the event - Event-level statistics - Market probabilities and slugs **Example**: "Show me all markets in the presidential-election-2024 event" ### 5. `list_tags` List all available tags/categories: - Discover market categories (Politics, Sports, Crypto, etc.) - Get tag IDs for filtering - Browse market taxonomy **Example**: "What categories of markets are available?" ### 6. `get_trades` Get recent trade activity from Data API: - Filter by market, event, or trade side (BUY/SELL) - Analyze trading patterns - View buy/sell ratio and volume **Example**: "Show me the last 20 trades for a specific market" ### 7. `analyze_market` Comprehensive market analysis combining multiple data sources: - Probability analysis with sentiment indicators - Market health scoring (liquidity & activity levels) - Optional trade data integration - AI-friendly insights for decision-making **Example**: "Give me a full analysis of trump-wins-2024" ## Prompts Included Prompts provide guided workflows for common use cases: ### 1. `analyze_market` Get comprehensive analysis of a specific market by slug. - **Args**: `market_slug` (e.g., "trump-wins-2024") - **Use**: Provides probabilities, trading activity, market health, and sentiment analysis ### 2. `find_trending` Discover the most active prediction markets. - **Args**: `category` (optional, e.g., "politics", "sports") - **Use**: Shows top 10 high-volume markets with analysis ### 3. `compare_event` Analyze and compare all markets within an event. - **Args**: `event_slug` (e.g., "presidential-election-2024") - **Use**: Compares related markets and identifies patterns ### 4. `market_discovery` Explore markets in a specific category. - **Args**: `category` (e.g., "crypto", "economics") - **Use**: Discovers markets with strong consensus or divided opinion ## Resources Exposed Resources provide direct access to curated market data: ### 1. `polymarket://trending` Currently trending markets with high volume and activity (top 20 by 24h volume) ### 2. `polymarket://categories` All available tags/categories for filtering markets (up to 100 tags) ### 3. `polymarket://featured` Featured events with multiple related markets (top 10 featured events) ## Use Cases ### Market Analysis Tools ``` "Analyze the top 10 political markets by volume and identify which have the strongest consensus vs divided opinion" ``` ### Trading Assistant ``` "Find high-liquidity markets with recent trading activity above $100k volume and show me the buy/sell ratios" ``` ### Event Outcome Analyzer ``` "Track all markets related to the 2024 election and summarize the current probabilities for each outcome" ``` ### Educational Platform ``` "Explain how prediction markets work using current Polymarket data and show examples of different market types" ``` ### Trend Detection ``` "Compare trading activity across sports markets today vs yesterday and identify any unusual patterns" ``` ## API Endpoints Used - **Gamma Markets API**: `https://gamma-api.polymarket.com` - `/markets` - Market search and discovery - `/markets/slug/{slug}` - Individual market data - `/events` - Event search - `/events/slug/{slug}` - Individual event data - `/tags` - Category taxonomy - **Data API**: `https://data-api.polymarket.com` - `/trades` - Trade history and activity ## Prerequisites - **Smithery API key**: Get yours at [smithery.ai/account/api-keys](https://smithery.ai/account/api-keys) - **Node.js** 18+ - No Polymarket authentication required (public read-only access) ## Getting Started ### Local Development 1. Install dependencies: ```bash npm install ``` 2. Start development server: ```bash npm run dev ``` 3. The server will be available in the Smithery playground. Try: - "Show me the most active prediction markets" - "Analyze the market for trump-wins-2024" - "What trading categories are available?" ### Building ```bash npm run build ``` Creates bundled server in `.smithery/` directory. ## Deployment to Smithery Deploy your Polymarket MCP server to Smithery for global access: 1. **Create a new GitHub repository** at [github.com/new](https://github.com/new) 2. **Initialize git and push to GitHub**: ```bash git init git add . git commit -m "Add Polymarket MCP server" git branch -M main git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git git push -u origin main ``` 3. **Deploy to Smithery** at [smithery.ai/new](https://smithery.ai/new): - Connect your GitHub repository - Smithery will auto-detect the configuration - Click "Deploy" 4. **Use in Claude**: Once deployed, the server will be available to use with Claude AI through the Smithery platform. ## Project Structure ``` polymarket-mcp/ ├── src/ │ └── index.ts # Main server implementation ├── package.json # Dependencies and scripts ├── smithery.yaml # Runtime specification ├── README.md # This file └── .smithery/ # Build output (generated) ``` ## Development The server is organized into: ### Type Definitions - `Market`, `Event`, `Tag`, `Trade` interfaces matching Polymarket API responses ### API Client (`PolymarketClient`) - `searchMarkets()` - Query markets with filters - `getMarket()` - Fetch single market by slug - `searchEvents()` - Query events with filters - `getEvent()` - Fetch single event by slug - `listTags()` - List all categories - `getTrades()` - Fetch recent trades ### Utility Functions - `formatMarketAnalysis()` - Format market data for Claude - `formatTradesSummary()` - Summarize trading activity ### MCP Tools - 7 tools with comprehensive schemas, error handling, and annotations - All tools are annotated as read-only, non-destructive, and idempotent - 4 prompts for common workflows (market analysis, trending, comparison, discovery) - 3 resources exposing curated data (trending markets, categories, featured events) ## Example Conversations ### Political Market Analysis ``` User: "What's the current probability for Trump winning the 2024 election?" Claude: [Uses get_market or search_markets to find relevant market] "Based on Polymarket data, the current probability is 52.3%..." ``` ### Market Discovery ``` User: "Find prediction markets related to cryptocurrency" Claude: [Uses list_tags to find crypto tag ID, then search_markets] "Found 23 active cryptocurrency markets. Here are the top 5..." ``` ### Trading Pattern Analysis ``` User: "Analyze recent trading activity for election markets" Claude: [Uses search_markets + get_trades to combine data] "Recent trading shows 67% buy orders vs 33% sell orders..." ``` ## Rate Limits Polymarket's public APIs have generous rate limits: - ~1,000 requests/hour for Gamma API - No authentication required - Consider implementing caching for production use ## Error Handling The server includes comprehensive error handling: - API errors are caught and returned with descriptive messages - 404 errors for missing markets/events - Network errors handled gracefully - Invalid parameters validated via Zod schemas ## Contributing Contributions are welcome! Some ideas: - Add caching layer for frequently accessed markets - Implement WebSocket support for real-time updates - Add more analytical tools (correlation, trend detection) - Create market comparison tools - Add support for historical data analysis ## Learn More - [Smithery Documentation](https://smithery.ai/docs) - [MCP Protocol Specification](https://modelcontextprotocol.io) - [Polymarket API Documentation](https://docs.polymarket.com) - [Polymarket Platform](https://polymarket.com) ## License ISC ## Acknowledgments Built with the Model Context Protocol by Anthropic and deployed via Smithery.