geo-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@geo-mcp search for GEO datasets related to breast cancer"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gene Expression Omnibus (GEO) MCP
Status: Beta. The MCP stdio and HTTP servers are both functional and in day-to-day use. The public tool surface is stable for the 0.1.x line; internal APIs and config defaults may still evolve. Please open an issue if you hit a regression.
A Model Context Protocol (MCP) server for accessing GEO (Gene Expression Omnibus) data through NCBI E-Utils API. The tool will enable you to search for GEO datasets, series, samples, platforms, and profiles for your LLM. Tested with Claude Desktop, chatGPT has no out of the box support for this tool yet. Claude will automatically use the tools if it fits the context.
Quick Install (pip)
install from pip
pip install geo-mcpinstall from source
git clone https://github.com/MCPmed/GEOmcp
cd GEOmcp
pip install -e .Related MCP server: NCBI Literature Search MCP Server
Configuration
Run init to create a config file
geo-mcp --initBy default this writes to $XDG_CONFIG_HOME/geomcp/config.json
(typically ~/.config/geomcp/config.json). If you already have a legacy
~/.geo-mcp/config.json from an older install, that location is still
honored and --init will update it in place so nothing gets orphaned.
The file contains:
{
"base_url": "https://eutils.ncbi.nlm.nih.gov/entrez/eutils",
"email": "your_email@example.com",
"api_key": "YOUR_API_KEY",
"download_dir": "~/.local/share/geomcp/downloads"
}emailis required by NCBI.api_keyis optional but recommended for higher rate limits (get one here).
You can also skip the config file entirely and pass values via env vars
(GEOMCP_EMAIL, GEOMCP_API_KEY, GEOMCP_BASE_URL, GEOMCP_DOWNLOAD_DIR)
or CLI flags (--email, --api-key, --download-dir, ...). Precedence,
highest wins: CLI flags → env vars → config.json → built-in defaults.
Running the Server
MCP stdio mode:
geo-mcpHTTP mode:
geo-mcp --http --port 8001
Claude Desktop Integration
Common Issue: spawn geo-mcp ENOENT
This error means Claude Desktop cannot find the geo-mcp command. This is usually a PATH issue.
Solution
Find the full path to the executable:
which geo-mcpExample output:
/Users/youruser/miniforge3/bin/geo-mcpUpdate your Claude config: Instead of just
"geo-bio-mcp", use the full path:{ "mcpServers": { "geo-mcp": { "command": "/Users/youruser/miniforge3/bin/geo-mcp", "env": { "CONFIG_PATH": "/Users/youruser/.geo-mcp/config.json" } } } }(Optional) Use a Conda Environment:
Activate your conda env and run
which geo-mcpto get the correct path.Use that path in your Claude config as above.
Restart Claude Desktop after updating the config.
Troubleshooting
If you see
command not found: geo-mcp, make sure you installed into the Python environment whosebindirectory is on yourPATH, or invoke the server with its full path.If the config file is missing,
geo-mcp --initwill create one. You can also run without a config by settingGEOMCP_EMAILin the environment.
HTTP API
With the server running via geo-mcp --http (default port 8001), the
following endpoints are exposed:
GET /— server statusGET /health— health checkGET /tools— list all registered MCP toolsPOST /tools/call— execute a tool with argumentsGET /events— server-sent events stream of tool callsGET /docs— interactive Swagger UI
Examples
# List available tools
curl http://localhost:8001/tools
# Search GEO Series
curl -X POST http://localhost:8001/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "search_geo_series",
"arguments": {"term": "breast cancer", "retmax": 5}
}'Available Tools
This MCP server provides access to all major GEO databases through the following tools:
Search Tools
search_geo- Universal GEO search across GSE/GSM/GPL/GDS records, with results bucketed by accession type. Passrecord_typesto filter.Example searches: "breast cancer", "GSE12345", "RNA-seq time course"
search_geo_profiles- Search gene expression profiles across different biological contextsExample searches: "cancer", "breast cancer", "p53", "apoptosis"
search_geo_datasets- Search curated gene expression datasetsExample searches: "diabetes", "Alzheimer's disease", "drug response", "tissue specific"
search_geo_series- Search original submitter-supplied gene expression seriesExample searches: "GSE12345", "microarray", "RNA-seq", "time course"
search_geo_samples- Search individual gene expression samplesExample searches: "GSM123456", "human", "mouse", "tumor", "normal"
search_geo_platforms- Search microarray platform definitionsExample searches: "Affymetrix", "Illumina", "Agilent", "GPL96"
Search Parameters
Each tool accepts:
term(required): Search term or query stringretmax(optional, default: 20): Maximum number of results to return
Example usage
For now just chat with claude desktop and it will use the tools automatically if it fits the context.
User: find a small brain dataset
Assistant: I'll help you find a small brain dataset from the GEO database. Let me search for brain-related datasets with a maximum of one result.
Assistant (system): search_geo_datasets
Assistant: I found a brain-related dataset for you:
Dataset: GSE290848
Title: Maternal Stress Triggers Early-Life Eczema via Fetal Mast Cell Reprogramming [10x Genomics Multiome ATAC + Gene Expression]
Species: Mouse (Mus musculus)
Samples: 8
Data type: ATAC-seq & gene expression (10x Genomics Multiome)
Publication date: 21 Jun 2025
This small dataset explores how prenatal stress affects neuro-immune circuits and mast-cell development.
Would you like me to download this dataset or search for others?
User: download GSE290848
Assistant: I'll download the GSE290848 dataset for you.
Assistant (system): download_geo_data
Assistant: Download complete.
Downloaded files
GSE290848_family.soft.gz— series, platform & sample infoGSE290848_metadata.xml— detailed study metadata
Location: ~/.local/share/geomcp/downloads/gse/GSE290848
Total size: 0.01 MB
The dataset is ready for analysis. Let me know if you’d like to explore it further.
Available Tools
11 toolscleanup_downloads_toolC
Clean up downloaded files
Inputs: geo_id, db_type.
download_geo_dataC
Download GEO data files (SOFT format)
Inputs: geo_id (required), db_type, output_dir.
get_download_statsB
Get download statistics and limits
Inputs: no named parameters.
get_download_statusB
Check if a GEO dataset has been downloaded
Inputs: geo_id (required), db_type.
list_downloaded_datasetsB
List all downloaded GEO datasets
Inputs: db_type.
search_geoC
Search GEO for all types of records (GSE, GSM, GPL, GDS)
Inputs: term (required), retmax, record_types.
search_geo_datasetsB
Search GEO Datasets (GDS) - curated gene expression datasets
Inputs: term (required), retmax.
search_geo_platformsC
Search GEO Platforms (GPL) - array/sequencing platforms
Inputs: term (required), retmax.
search_geo_profilesB
Search GEO Profiles database for gene expression profiles
Inputs: term (required), retmax.
search_geo_samplesB
Search GEO Samples (GSM) - individual samples
Inputs: term (required), retmax.
search_geo_seriesC
Search GEO Series (GSE) - complete experiments
Inputs: term (required), retmax.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource or action: search tools are differentiated by GEO record type (series, samples, platforms, datasets, profiles) plus a general search; download and management tools are clearly distinct (download, stats, status, list, cleanup). No overlapping purposes.
Most tools follow a consistent verb_noun pattern (e.g., download_geo_data, search_geo_series). The outlier is cleanup_downloads_tool, which uses 'cleanup' instead of 'clean' and has a '_tool' suffix, breaking the pattern slightly.
11 tools is well-scoped for a GEO MCP server, covering search across key record types, download operations, and dataset management. The number feels appropriate—neither too few nor excessive.
The server provides comprehensive search, download, and management capabilities for GEO data. Potential gaps include the absence of an explicit delete operation for individual datasets (cleanup is a blanket operation) and lack of upload or update functionality, but these are peripheral to the primary purpose.
Maintenance
Related MCP Connectors
NCBI Datasets — the US National Library of Medicine's genome, gene and taxonomy reference service…
Search public biomedical datasets, measured results, papers, trials and drug evidence with sources.
Search 24M+ biomedical journal abstracts (20M+ in PubMed) by meaning or by exact terms.
Search biomedical literature, get article details, find related articles, and explore MeSH terms
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceProvides access to NCBI's scientific databases including E-utilities, PubChem, and PMC APIs for biomedical literature search, molecular data retrieval, and research through natural language queries.3-
- FlicenseNot gradedqualityDmaintenanceProvides seamless access to over 35 million PubMed scientific articles through natural language queries for research discovery and analysis. It enables tools for advanced searches, retrieving article details, and exploring related research within the life sciences and biomedical fields.13-
- AlicenseCqualityDmaintenanceProvides AI-powered access to major biological databases for GWAS and bioinformatics research. Enables natural language queries for protein, gene, variant, pathway, and drug discovery analysis.441MIT

igvf-portal-mcpofficial
AlicenseNot gradedqualityCmaintenanceEnables AI agents to search, filter, download files, and generate reports from the IGVF Data Portal using natural language commands.2MIT