PolyMarket MCP Server

Instructions

Implementation Reference

• src/polymarket_mcp/server.py:249-282 (handler)

  The main handler logic for the 'list-markets' tool within the @server.call_tool() function. It fetches markets from ClobClient, parses and filters the response based on status, applies pagination using offset and limit, formats the data, and returns it as text content.

  elif name == "list-markets":
      status = arguments.get("status")
      
      # Get markets using CLOB client
      markets_data = client.get_markets()
  
      # Handle string response (if the response is a JSON string)
      if isinstance(markets_data, str):
          try:
              markets_data = json.loads(markets_data)
          except json.JSONDecodeError:
              return [types.TextContent(type="text", text="Error: Invalid response format from API")]
      
      # Ensure we have a list of markets
      if not isinstance(markets_data, list):
          if isinstance(markets_data, dict) and 'data' in markets_data:
              markets_data = markets_data['data']
          else:
              return [types.TextContent(type="text", text="Error: Unexpected response format from API")]
      
      # Filter by status if specified
      if status:
          markets_data = [
              market for market in markets_data 
              if isinstance(market, dict) and market.get('status', '').lower() == status.lower()
          ]
      
      # Apply pagination
      offset = arguments.get("offset", 0)
      limit = arguments.get("limit", 10)
      markets_data = markets_data[offset:offset + limit]
      
      formatted_list = format_market_list(markets_data)
      return [types.TextContent(type="text", text=formatted_list)]

• src/polymarket_mcp/server.py:58-84 (registration)

  Registration of the 'list-markets' tool in the @server.list_tools() handler, defining the tool name, description, and input schema for validation.

  types.Tool(
      name="list-markets",
      description="Get a list of prediction markets with optional filters",
      inputSchema={
          "type": "object",
          "properties": {
              "status": {
                  "type": "string",
                  "description": "Filter by market status (e.g., open, closed, resolved)",
                  "enum": ["active", "resolved"],
              },
              "limit": {
                  "type": "integer",
                  "description": "Number of markets to return (default: 10)",
                  "default": 10,
                  "minimum": 1,
                  "maximum": 100
              },
              "offset": {
                  "type": "integer",
                  "description": "Number of markets to skip (for pagination)",
                  "default": 0,
                  "minimum": 0
              }
          },
      },
  ),

• src/polymarket_mcp/server.py:142-179 (helper)

  Helper function to format the list of markets into a human-readable string, extracting various fields like condition ID, description, volume, etc., and handling formatting errors.

  def format_market_list(markets_data: list) -> str:
      """Format list of markets into a concise string."""
      try:
          if not markets_data:
              return "No markets available"
              
          formatted_markets = ["Available Markets:\n"]
          
          for market in markets_data:
              try:
                  volume = float(market.get('volume', 0))
                  volume_str = f"${volume:,.2f}"
              except (ValueError, TypeError):
                  volume_str = f"${market.get('volume', 0)}"
                  
              formatted_markets.append(
                  f"Condition ID: {market.get('condition_id', 'N/A')}\n"
                  f"Description: {market.get('description', 'N/A')}\n"
                  f"Category: {market.get('category', 'N/A')}\n"
                  f"Tokens: {market.get('question', 'N/A')}\n"
                  f"Question: {market.get('active', 'N/A')}\n"
                  f"Rewards: {market.get('rewards', 'N/A')}\n"
                  f"Active: {market.get('active', 'N/A')}\n"
                  f"Closed: {market.get('closed', 'N/A')}\n"
                  f"Slug: {market.get('market_slug', 'N/A')}\n"
                  f"Min Incentive size: {market.get('min_incentive_size', 'N/A')}\n"
                  f"Max Incentive size: {market.get('max_incentive_spread', 'N/A')}\n"
                  f"End date: {market.get('end_date_iso', 'N/A')}\n"
                  f"Start time: {market.get('game_start_time', 'N/A')}\n"
                  f"Min order size: {market.get('minimum_order_size', 'N/A')}\n"
                  f"Max tick size: {market.get('minimum_tick_size', 'N/A')}\n"
                  f"Volume: {volume_str}\n"
                  "---\n"
              )
          
          return "\n".join(formatted_markets)
      except Exception as e:
          return f"Error formatting markets list: {str(e)}"