UCSC Genome Browser MCP Server

Instructions

Implementation Reference

• ucsc-genome-mcp.py:340-353 (handler)

  Executes the find_genome tool by mapping input arguments to API parameters, building the UCSC /findGenome API URL, making an asynchronous HTTP request, and returning the JSON result.

  if name == "find_genome":
      params = {
          "q": arguments["query"],
          "browser": arguments.get("browser"),
          "statsOnly": 1 if arguments.get("stats_only") else None,
          "year": arguments.get("year"),
          "category": arguments.get("category"),
          "status": arguments.get("status"),
          "level": arguments.get("level"),
          "maxItemsOutput": arguments.get("max_items")
      }
      url = build_api_url("/findGenome", params)
      result = await make_api_request(url)

• ucsc-genome-mcp.py:54-94 (schema)

  Input schema defining parameters for the find_genome tool, including query (required), optional filters like browser, stats_only, year, category, status, level, and max_items.

  inputSchema={
      "type": "object",
      "properties": {
          "query": {
              "type": "string",
              "description": "Search string to find genomes (e.g., 'dog', 'GRCh38', 'GCF_028858775.2')"
          },
          "browser": {
              "type": "string",
              "enum": ["mustExist", "mayExist", "notExist"],
              "description": "Filter by browser availability (default: mustExist)"
          },
          "stats_only": {
              "type": "boolean",
              "description": "Only show statistics about search results"
          },
          "year": {
              "type": "integer",
              "description": "Filter results by year"
          },
          "category": {
              "type": "string",
              "enum": ["reference", "representative"],
              "description": "Filter by NCBI category"
          },
          "status": {
              "type": "string",
              "enum": ["reference", "representative"],
              "description": "Filter by NCBI status"
          },
          "level": {
              "type": "string",
              "enum": ["complete", "chromosome", "scaffold", "contig"],
              "description": "Filter by NCBI assembly level"
          },
          "max_items": {
              "type": "integer",
              "description": "Maximum number of items to return (default: 1000000, use -1 for max)"
          }
      },
      "required": ["query"]

• ucsc-genome-mcp.py:51-96 (registration)

  Registers the find_genome tool with the MCP server in the list_tools() function, specifying name, description, and input schema.

  Tool(
      name="find_genome",
      description="Search for a genome in the UCSC browser using a search string. Supports advanced search with +word (force inclusion), -word (exclusion), and word* (wildcard).",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Search string to find genomes (e.g., 'dog', 'GRCh38', 'GCF_028858775.2')"
              },
              "browser": {
                  "type": "string",
                  "enum": ["mustExist", "mayExist", "notExist"],
                  "description": "Filter by browser availability (default: mustExist)"
              },
              "stats_only": {
                  "type": "boolean",
                  "description": "Only show statistics about search results"
              },
              "year": {
                  "type": "integer",
                  "description": "Filter results by year"
              },
              "category": {
                  "type": "string",
                  "enum": ["reference", "representative"],
                  "description": "Filter by NCBI category"
              },
              "status": {
                  "type": "string",
                  "enum": ["reference", "representative"],
                  "description": "Filter by NCBI status"
              },
              "level": {
                  "type": "string",
                  "enum": ["complete", "chromosome", "scaffold", "contig"],
                  "description": "Filter by NCBI assembly level"
              },
              "max_items": {
                  "type": "integer",
                  "description": "Maximum number of items to return (default: 1000000, use -1 for max)"
              }
          },
          "required": ["query"]
      }
  ),

• ucsc-genome-mcp.py:27-36 (helper)

  Helper function to construct UCSC API URLs from endpoint and parameters, filtering None values and using semicolon-separated params.

  def build_api_url(endpoint: str, params: dict[str, Any]) -> str:
      """Build the complete API URL with parameters."""
      # Filter out None values
      filtered_params = {k: v for k, v in params.items() if v is not None}
      
      # Convert parameters to URL format (using semicolons as per UCSC API spec)
      if filtered_params:
          param_str = ";".join(f"{k}={v}" for k, v in filtered_params.items())
          return f"{BASE_URL}{endpoint}?{param_str}"
      return f"{BASE_URL}{endpoint}"

• ucsc-genome-mcp.py:39-44 (helper)

  Helper function to perform asynchronous HTTP GET request to UCSC API URL and parse JSON response.

  async def make_api_request(url: str) -> dict[str, Any]:
      """Make an HTTP request to the UCSC API and return JSON response."""
      async with httpx.AsyncClient(timeout=30.0) as client:
          response = await client.get(url)
          response.raise_for_status()
          return response.json()