polymarket-mcp-server

# Polymarket MCP Server > Skill by [ara.so](https://ara.so) — MCP Skills collection. AI-powered MCP server that enables Claude to autonomously trade, analyze, and manage positions on Polymarket prediction markets. Provides 45 comprehensive tools across market discovery, analysis, trading, portfolio management, and real-time monitoring with WebSocket support. ## Installation ### Quick Start (DEMO Mode - No Wallet Required) ```bash # Clone and install git clone https://github.com/caiovicentino/polymarket-mcp-server.git cd polymarket-mcp-server ./quickstart.sh # Or automated one-liner curl -sSL https://raw.githubusercontent.com/caiovicentino/polymarket-mcp-server/main/quickstart.sh | bash ``` ### Full Installation (Trading Enabled) ```bash # Use automated installer ./install.sh # Or manual installation python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -e . ``` ### Configuration Create `.env` file: ```bash cp .env.example .env ``` **DEMO Mode (Read-Only):** ```env DEMO_MODE=true ``` **Full Trading Mode:** ```env # Required POLYGON_PRIVATE_KEY=${POLYGON_PRIVATE_KEY} POLYGON_ADDRESS=${POLYGON_ADDRESS} # Optional Safety Limits MAX_ORDER_SIZE_USD=1000 MAX_TOTAL_EXPOSURE_USD=5000 MAX_POSITION_SIZE_PER_MARKET=2000 MIN_LIQUIDITY_REQUIRED=10000 MAX_SPREAD_TOLERANCE=0.05 REQUIRE_CONFIRMATION_ABOVE_USD=500 ENABLE_AUTONOMOUS_TRADING=true ``` ### Claude Desktop Integration Add to `claude_desktop_config.json`: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "polymarket": { "command": "/absolute/path/to/venv/bin/python", "args": ["-m", "polymarket_mcp.server"], "cwd": "/absolute/path/to/polymarket-mcp-server", "env": { "POLYGON_PRIVATE_KEY": "${POLYGON_PRIVATE_KEY}", "POLYGON_ADDRESS": "${POLYGON_ADDRESS}" } } } } ``` ## Tool Categories ### 1. Market Discovery (8 Tools) #### Search Markets ```python # Tool: search_markets { "query": "Trump election", "limit": 10, "offset": 0 } ``` #### Get Trending Markets ```python # Tool: get_trending_markets { "period": "24h", # "24h", "7d", or "30d" "limit": 20 } ``` #### Markets Closing Soon ```python # Tool: get_markets_closing_soon { "hours": 24, "limit": 10 } ``` #### Category-Specific Markets ```python # Tool: get_markets_by_category { "category": "Politics", # Politics, Sports, Crypto, Pop Culture "limit": 20 } ``` ### 2. Market Analysis (10 Tools) #### Get Market Details ```python # Tool: get_market_details { "market_id": "0x1234..." } ``` #### Analyze Market Opportunity (AI-Powered) ```python # Tool: analyze_market_opportunity { "market_id": "0x1234...", "analysis_depth": "deep" # "quick" or "deep" } # Returns: BUY/SELL/HOLD recommendation with reasoning ``` #### Get Orderbook Depth ```python # Tool: get_orderbook_depth { "token_id": "0x5678..." } ``` #### Compare Markets ```python # Tool: compare_markets { "market_ids": ["0x1234...", "0x5678...", "0x9abc..."] } ``` #### Calculate Spread ```python # Tool: calculate_spread { "token_id": "0x5678..." } ``` ### 3. Trading (12 Tools) #### Place Limit Order ```python # Tool: place_limit_order { "token_id": "0x5678...", "side": "BUY", # or "SELL" "price": 0.65, "size": 100, "time_in_force": "GTC" # GTC, GTD, FOK, FAK } ``` #### Place Market Order ```python # Tool: place_market_order { "token_id": "0x5678...", "side": "BUY", "amount": 50 } ``` #### Smart Trade (AI-Powered) ```python # Tool: smart_trade { "instruction": "Buy $200 worth of Yes on Trump 2024 election if price below 0.60", "strategy": "passive" # aggressive, passive, or mid } # Automatically parses instruction and executes optimal trade ``` #### Get AI Suggested Prices ```python # Tool: get_ai_suggested_prices { "token_id": "0x5678...", "side": "BUY", "strategy": "mid" # aggressive, passive, or mid } ``` #### Cancel Order ```python # Tool: cancel_order { "order_id": "0xabcd..." } ``` #### Get Open Orders ```python # Tool: get_open_orders { "market_id": "0x1234..." # Optional filter } ``` ### 4. Portfolio Management (8 Tools) #### Get Portfolio Summary ```python # Tool: get_portfolio_summary {} # Returns: total value, positions, P&L, risk metrics ``` #### Get Active Positions ```python # Tool: get_active_positions { "market_id": "0x1234..." # Optional filter } ``` #### Calculate P&L ```python # Tool: calculate_pnl { "position_id": "0x5678...", "include_unrealized": true } ``` #### Analyze Portfolio Risk ```python # Tool: analyze_portfolio_risk {} # Returns: concentration risk, liquidity risk, diversification score ``` #### Optimize Portfolio (AI-Powered) ```python # Tool: optimize_portfolio { "risk_profile": "balanced", # conservative, balanced, or aggressive "target_allocation": { "Politics": 0.4, "Sports": 0.3, "Crypto": 0.3 } } # Returns: rebalancing suggestions with rationale ``` #### Get Trade History ```python # Tool: get_trade_history { "start_date": "2024-01-01", "end_date": "2024-12-31", "market_id": "0x1234..." # Optional } ``` ### 5. Real-Time Monitoring (7 Tools) #### Subscribe to Market Updates ```python # Tool: subscribe_to_market { "market_id": "0x1234...", "channels": ["price", "orderbook", "trades"] } ``` #### Subscribe to User Orders ```python # Tool: subscribe_to_user_orders {} # Monitors all your order status changes ``` #### Get WebSocket Status ```python # Tool: get_websocket_status {} # Returns: connection state, subscriptions, message counts ``` #### Unsubscribe from Market ```python # Tool: unsubscribe_from_market { "market_id": "0x1234..." } ``` ## Python API Usage ### Direct Python Integration ```python from polymarket_mcp.client import PolymarketClient from decimal import Decimal import os # Initialize client client = PolymarketClient( private_key=os.getenv("POLYGON_PRIVATE_KEY"), polygon_address=os.getenv("POLYGON_ADDRESS") ) # Search markets markets = client.search_markets(query="election", limit=5) for market in markets: print(f"{market['question']} - Volume: ${market['volume24h']}") # Get market analysis market_id = markets[0]['id'] analysis = client.analyze_market_opportunity( market_id=market_id, analysis_depth="deep" ) print(f"Recommendation: {analysis['recommendation']}") print(f"Reasoning: {analysis['reasoning']}") # Place order with safety checks token_id = markets[0]['tokens'][0]['id'] order = client.place_limit_order( token_id=token_id, side="BUY", price=Decimal("0.55"), size=100, time_in_force="GTC" ) print(f"Order placed: {order['id']}") # Monitor portfolio portfolio = client.get_portfolio_summary() print(f"Total Value: ${portfolio['total_value_usd']}") print(f"Unrealized P&L: ${portfolio['unrealized_pnl']}") # Get real-time updates via WebSocket client.subscribe_to_market( market_id=market_id, channels=["price", "orderbook"] ) ``` ### Trading Strategies Example ```python from polymarket_mcp.client import PolymarketClient from decimal import Decimal class SimpleArbitrageBot: def __init__(self, client: PolymarketClient): self.client = client self.min_spread = Decimal("0.05") # 5% minimum spread def find_arbitrage_opportunities(self): """Find markets with high spreads""" trending = self.client.get_trending_markets(period="24h", limit=50) opportunities = [] for market in trending: for token in market['tokens']: spread = self.client.calculate_spread(token['id']) if spread['spread_percentage'] > float(self.min_spread): opportunities.append({ 'market': market['question'], 'token_id': token['id'], 'spread': spread['spread_percentage'], 'best_bid': spread['best_bid'], 'best_ask': spread['best_ask'] }) return sorted(opportunities, key=lambda x: x['spread'], reverse=True) def execute_trade(self, opportunity): """Execute trade on identified opportunity""" # Get AI-suggested optimal price suggested = self.client.get_ai_suggested_prices( token_id=opportunity['token_id'], side="BUY", strategy="mid" ) # Place order order = self.client.place_limit_order( token_id=opportunity['token_id'], side="BUY", price=Decimal(str(suggested['suggested_price'])), size=100, time_in_force="GTC" ) return order # Usage client = PolymarketClient( private_key=os.getenv("POLYGON_PRIVATE_KEY"), polygon_address=os.getenv("POLYGON_ADDRESS")