Purpose
ucsc-genome-mcp is a Model Context Protocol (MCP) server designed to enable large language model applications to query the UCSC Genome Browser's genomic data, sequences, data tracks, and metadata. By wrapping the UCSC Genome Browser API, it allows LLMs to invoke a variety of genomics-related tools, suitable for scenarios such as genomic research, variant analysis, comparative genomics, sequence analysis, data discovery, and teaching.
Main Capabilities
The server exposes 12 tools, covering the main endpoints of the UCSC Genome Browser API:
-
List and Discovery Tools:
- find_genome: Search for genomes using keywords, accession numbers, or organism names.
- list_public_hubs: List all available public track hubs.
- list_ucsc_genomes: List all UCSC database genomes.
- list_genark_genomes: List GenArk assembly hub genomes.
- list_hub_genomes: List genomes in a specific hub.
- list_files: List downloadable files for a genome.
- list_tracks: List data tracks in a genome or hub.
- list_chromosomes: List chromosomes in a genome or track.
- list_schema: Get the field definitions of a track.
-
Data Retrieval Tools:
- get_sequence: Retrieve DNA sequences from a genome.
- get_track_data: Retrieve track data (genes, variants, annotations, etc.).
- search_genome: Search within a genome assembly.
Usage
- Environment requirements: Python 3.10 or later.
- Installation: Install from source.
- Dependencies: mcp>=0.9.0 (Model Context Protocol SDK), httpx>=0.27.0 (HTTP client for API requests).
- Running: The server communicates via stdio, following the MCP protocol.
- Integration with Claude Desktop: In the Claude Desktop configuration file, add the configuration.
- MacOS configuration file path: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows configuration file path: %APPDATA%/Claude/claude_desktop_config.json
Applicable Scenarios
- Genomic Research: Query gene positions, sequences, and annotations.
- Variant Analysis: Retrieve SNP and variant data.
- Comparative Genomics: Access data for multiple species.
- Sequence Analysis: Obtain DNA/RNA sequences for analysis.
- Data Discovery: Find available datasets and assemblies.
- Teaching: Learn genomics through interactive queries.
Limitations and Notes
- Request Rate: A maximum of 1 request per second is recommended. The API has a botDelay system to prevent overload; excessive queries may result in restricted access.
- Coordinate System: The start coordinate is 0-based (the first base is 0), and the end coordinate is 1-based (exclusive). For example, start=0, end=10 retrieves the first 10 bases.
- Supported Track Types: The get_track_data tool supports many types, including bed, bigBed, bigWig, genePred, bigGenePred, bigChain, bigPsl, bigMaf, narrowPeak, bigNarrowPeak, wiggle/wig, barChart/bigBarChart, interact/bigInteract, and more.
- Large Dataset Handling: For tracks with more than 1 million items, use pagination; query by chromosome; use start/end coordinates to specify a smaller region.
- Error Handling: The server handles HTTP errors (404, 500, etc.), invalid parameters, nonexistent genomes/tracks/chromosomes, and request timeouts (default 30 seconds), and returns descriptive error messages in text responses.
- API Request Address: All requests are sent to https://api.genome.ucsc.edu。
- Terms of Use: This project interacts with the UCSC Genome Browser, which has its own terms of use, detailed at https://genome.ucsc.edu/conditions.html。UCSC For issues with the Genome Browser API, please contact UCSC; for issues with this MCP server, please submit an issue in the repository.
Project Structure Notes
- Adding a new endpoint: add the tool definition in list_tools(), add the handler in call_tool(), and update the examples in the README.
- Individual endpoints can be tested manually.
Version
Initial version, supporting all major UCSC Genome Browser API endpoints, with 12 tools covering listing, discovery, and data retrieval, including complete documentation and examples.
