Skip to main content
Glama

Gene Expression Omnibus (GEO) MCP

PyPI version Python License MCP GEO

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-mcp

install 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 --init

By 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"
}
  • email is required by NCBI.

  • api_key is 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-mcp
  • HTTP 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

  1. Find the full path to the executable:

    which geo-mcp

    Example output: /Users/youruser/miniforge3/bin/geo-mcp

  2. Update 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"
          }
        }
      }
    }
  3. (Optional) Use a Conda Environment:

    • Activate your conda env and run which geo-mcp to get the correct path.

    • Use that path in your Claude config as above.

  4. Restart Claude Desktop after updating the config.


Troubleshooting

  • If you see command not found: geo-mcp, make sure you installed into the Python environment whose bin directory is on your PATH, or invoke the server with its full path.

  • If the config file is missing, geo-mcp --init will create one. You can also run without a config by setting GEOMCP_EMAIL in the environment.


HTTP API

With the server running via geo-mcp --http (default port 8001), the following endpoints are exposed:

  • GET / — server status

  • GET /health — health check

  • GET /tools — list all registered MCP tools

  • POST /tools/call — execute a tool with arguments

  • GET /events — server-sent events stream of tool calls

  • GET /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. Pass record_types to filter.

    • Example searches: "breast cancer", "GSE12345", "RNA-seq time course"

  • search_geo_profiles - Search gene expression profiles across different biological contexts

    • Example searches: "cancer", "breast cancer", "p53", "apoptosis"

  • search_geo_datasets - Search curated gene expression datasets

    • Example searches: "diabetes", "Alzheimer's disease", "drug response", "tissue specific"

  • search_geo_series - Search original submitter-supplied gene expression series

    • Example searches: "GSE12345", "microarray", "RNA-seq", "time course"

  • search_geo_samples - Search individual gene expression samples

    • Example searches: "GSM123456", "human", "mouse", "tumor", "normal"

  • search_geo_platforms - Search microarray platform definitions

    • Example searches: "Affymetrix", "Illumina", "Agilent", "GPL96"

Search Parameters

Each tool accepts:

  • term (required): Search term or query string

  • retmax (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 info

  • GSE290848_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 tools
cleanup_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

    B3.3/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
      -
    • A
      license
      C
      quality
      D
      maintenance
      Provides 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.
      44
      1
      MIT

    Appeared in Searches