UCSC Genome Browser MCP Server

1# UCSC Genome Browser MCP Server
2 
3A Model Context Protocol (MCP) server that provides comprehensive access to the UCSC Genome Browser API. This server enables LLM applications to query genomic data, sequences, tracks, and metadata from the UCSC Genome Browser.
4 
5## Features
6 
7This MCP server exposes 12 tools that cover all major UCSC Genome Browser API endpoints:
8 
9### Listing & Discovery Tools
10- **find_genome** - Search for genomes using keywords, accession IDs, or organism names
11- **list_public_hubs** - List all available public track hubs
12- **list_ucsc_genomes** - List all UCSC database genomes
13- **list_genark_genomes** - List GenArk assembly hub genomes
14- **list_hub_genomes** - List genomes from a specific hub
15- **list_files** - List downloadable files for a genome
16- **list_tracks** - List data tracks in a genome or hub
17- **list_chromosomes** - List chromosomes in a genome or track
18- **list_schema** - Get schema/field definitions for a track
19 
20### Data Retrieval Tools
21- **get_sequence** - Retrieve DNA sequences from genomes
22- **get_track_data** - Get track data (genes, variants, annotations, etc.)
23- **search_genome** - Search within a genome assembly
24 
25## Installation
26 
27### Prerequisites
28- Python 3.10 or higher
29- pip
30 
31### Install from source
32 
33```bash
34# Clone or download the repository
35cd ucsc-genome-mcp-server
36 
37# Install in development mode
38pip install -e .
39```
40 
41### Required Dependencies
42- `mcp>=0.9.0` - Model Context Protocol SDK
43- `httpx>=0.27.0` - HTTP client for API requests
44 
45## Usage
46 
47### Running the Server
48 
49The server communicates over stdio, following the MCP protocol:
50 
51```bash
52python ucsc_genome_mcp_server.py
53```
54 
55### Configuration with Claude Desktop
56 
57Add this to your Claude Desktop configuration file:
58 
59**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
60**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
61 
62```json
63{
64  "mcpServers": {
65    "ucsc-genome-browser": {
66      "command": "/Users/You/.local/bin/uv",
67      "args": [
68        "--directory",
69        "/Users/Path/To/Repository/ucsc-genome-mcp",
70        "run",
71        "ucsc-genome-mcp.py"
72      ],
73      "env": {},
74      "metadata": {
75        "description": "UCSC Genome Browser API",
76        "version": "1.0.0"        
77      }
78  }
79}
80```
81 
82## Tool Examples
83 
84### 1. Find Genomes
85 
86Search for dog genomes:
87```json
88{
89  "query": "dog"
90}
91```
92 
93Search with advanced operators:
94```json
95{
96  "query": "+white +rhino* -southern",
97  "browser": "mustExist"
98}
99```
100 
101### 2. List Available Tracks
102 
103List all tracks for human genome (hg38):
104```json
105{
106  "genome": "hg38"
107}
108```
109 
110List tracks without container information:
111```json
112{
113  "genome": "hg38",
114  "track_leaves_only": true
115}
116```
117 
118### 3. Get DNA Sequence
119 
120Get entire mitochondrial chromosome:
121```json
122{
123  "genome": "hg38",
124  "chrom": "chrM"
125}
126```
127 
128Get specific region:
129```json
130{
131  "genome": "hg38",
132  "chrom": "chrM",
133  "start": 4321,
134  "end": 5678
135}
136```
137 
138Get reverse complement:
139```json
140{
141  "genome": "hg38",
142  "chrom": "chrM",
143  "start": 4321,
144  "end": 5678,
145  "reverse_complement": true
146}
147```
148 
149### 4. Get Track Data
150 
151Get gene annotations for a region:
152```json
153{
154  "genome": "hg38",
155  "track": "knownGene",
156  "chrom": "chr1",
157  "start": 47000,
158  "end": 48000
159}
160```
161 
162Get track data from an assembly hub:
163```json
164{
165  "hub_url": "http://hgdownload.gi.ucsc.edu/hubs/mouseStrains/hub.txt",
166  "genome": "CAST_EiJ",
167  "track": "assembly",
168  "chrom": "chr1"
169}
170```
171 
172### 5. Search Within a Genome
173 
174Search for BRCA1 in human genome:
175```json
176{
177  "search": "brca1",
178  "genome": "hg38"
179}
180```
181 
182Search only in help documentation:
183```json
184{
185  "search": "bigBed",
186  "genome": "hg38",
187  "categories": "helpDocs"
188}
189```
190 
191## API Details
192 
193### Base URL
194All requests go to: `https://api.genome.ucsc.edu`
195 
196### Rate Limits
197- Recommended: Maximum 1 request per second
198- The API has a botDelay system to prevent overload
199- Excessive queries may result in restricted access
200 
201### Coordinate Systems
202- **Start coordinates**: 0-based (first base is 0)
203- **End coordinates**: 1-based (exclusive)
204- Example: `start=0, end=10` retrieves the first 10 bases
205 
206### Supported Track Types
207The `get_track_data` tool supports these track types:
208- bed, bigBed, bigWig
209- genePred, bigGenePred
210- bigChain, bigPsl, bigMaf
211- narrowPeak, bigNarrowPeak
212- wiggle/wig, barChart/bigBarChart
213- interact/bigInteract
214- And many more...
215 
216## Advanced Features
217 
218### Working with Large Datasets
219 
220For tracks with over 1 million items, use pagination:
221 
2221. Query by chromosome:
223```json
224{
225  "genome": "hg19",
226  "track": "knownGene",
227  "chrom": "chr1"
228}
229```
230 
2312. Use start/end coordinates for smaller regions:
232```json
233{
234  "genome": "hg19",
235  "track": "knownGene",
236  "chrom": "chr1",
237  "start": 1000000,
238  "end": 2000000
239}
240```
241 
242### Working with Track Hubs
243 
244Track hubs allow accessing external genomic data:
245 
246```json
247{
248  "hub_url": "http://hgdownload.gi.ucsc.edu/hubs/mouseStrains/hub.txt",
249  "genome": "CAST_EiJ",
250  "track": "ensGene",
251  "chrom": "chr1"
252}
253```
254 
255## Error Handling
256 
257The server handles various error conditions:
258- HTTP errors (404, 500, etc.)
259- Invalid parameters
260- Non-existent genomes/tracks/chromosomes
261- Request timeouts (30 second default)
262 
263Errors are returned as text responses with descriptive messages.
264 
265## Use Cases
266 
267This MCP server enables LLM applications to:
268 
2691. **Genomic Research**: Query gene locations, sequences, and annotations
2702. **Variant Analysis**: Retrieve SNP and variant data
2713. **Comparative Genomics**: Access data from multiple species
2724. **Sequence Analysis**: Get DNA/RNA sequences for analysis
2735. **Data Discovery**: Find available datasets and assemblies
2746. **Educational**: Learn about genomics through interactive queries
275 
276## API Documentation
277 
278For complete API documentation, visit:
279https://genome.ucsc.edu/goldenpath/help/api.html
280 
281## License
282 
283This project interfaces with the UCSC Genome Browser, which has its own terms of use:
284https://genome.ucsc.edu/conditions.html
285 
286## Support
287 
288For issues with the UCSC Genome Browser API, contact UCSC.
289For issues with this MCP server, please file an issue in the repository.
290 
291## Development
292 
293### Project Structure
294```
295.
296├── ucsc_genome_mcp_server.py  # Main server implementation
297├── pyproject.toml             # Project metadata and dependencies
298└── README.md                  # This file
299```
300 
301### Adding New Tools
302 
303To add new endpoints:
304 
3051. Add the tool definition in `list_tools()`
3062. Add the handler in `call_tool()`
3073. Update this README with examples
308 
309### Testing
310 
311Test individual endpoints manually:
312```bash
313# Using curl
314curl -L 'https://api.genome.ucsc.edu/list/ucscGenomes'
315 
316# Using wget
317wget -O- 'https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chrM;start=4321;end=5678'
318```
319 
320## Changelog
321 
322### Version 0.1.0
323- Initial release
324- Support for all major UCSC Genome Browser API endpoints
325- 12 tools covering listing, discovery, and data retrieval
326- Full documentation and examples
327