| Name | geo-mcp JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Model Context Protocol (MCP) server for accessing GEO (Gene Expression Omnibus) data through NCBI E-Utils API |
| upload_time | 2025-07-30 11:49:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
bioinformatics
e-utils
gene-expression
geo
mcp
ncbi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gene Expression Omnibus (GEO) MCP
<div align="center">
<img src="https://www.ncbi.nlm.nih.gov/geo/img/geo_main.gif" alt="GEO Logo" width="200"/>
<br/>
<em>Gene Expression Omnibus (GEO) - A public functional genomics data repository</em>
</div>
[](https://pypi.org/project/geo-bio-mcp/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](https://www.ncbi.nlm.nih.gov/geo/)
> ⚠️ **Development Warning** ⚠️
>
> **This project is currently in active development and is not yet production-ready.**
>
> - The MCP stdio server is functional but may have bugs or incomplete features
> - The HTTP server is in early development phase and has **not been properly tested**
> - API endpoints and functionality may change without notice
> - Use at your own risk and report any issues you encounter
>
> We recommend testing thoroughly in a development environment before using in production.
A Model Context Protocol (MCP) server for accessing [GEO (Gene Expression Omnibus)](https://www.ncbi.nlm.nih.gov/geo/) 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
```bash
pip install geo-bio-mcp
```
install from source
```bash
# Clone the repo (if not already)
git clone <repo-url>
cd GEO_MCP
pip install -e .
```
## Configuration
Run init to create a config file
```bash
geo-bio-mcp --init
```
This will create a config file at `~/.geo-bio-mcp/config.json` (auto-created on first run if missing).
This file will contain the following:
```json
{
"base_url": "https://eutils.ncbi.nlm.nih.gov/entrez/eutils",
"email": "your_email@example.com",
"api_key": "YOUR_API_KEY"
}
```
It will also print out a configuration template for your claude desktop configuration file.
- `email` is required by NCBI.
- `api_key` is optional but recommended for higher rate limits ([get one here](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)).
## Running the Server
- **MCP stdio mode:**
```bash
geo-bio-mcp
```
- **HTTP mode:**
```bash
geo-bio-mcp --http --port 8001
```
## Claude Desktop Integration
### Common Issue: `spawn geo-bio-mcp ENOENT`
This error means Claude Desktop cannot find the `geo-bio-mcp` command. This is usually a PATH issue.
### Solution
1. **Find the full path to the executable:**
```bash
which geo-bio-mcp
```
Example output: `/Users/youruser/miniforge3/bin/geo-bio-mcp`
2. **Update your Claude config:**
Instead of just `"geo-bio-mcp"`, use the full path:
```json
{
"mcpServers": {
"geo-mcp": {
"command": "/Users/youruser/miniforge3/bin/geo-bio-mcp",
"env": {
"CONFIG_PATH": "/Users/youruser/.geo-mcp/config.json"
}
}
}
}
```
3. **(Optional) Use a Conda Environment:**
- Activate your conda env and run `which geo-bio-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-bio-mcp`, make sure you installed with the correct Python/conda environment and that its `bin` directory is in your PATH.
- If the config file is missing, it will be auto-created on first run, or you can copy the template from `geo_mcp_server/config_template.json`.
---
## Usage
### MCP Server (stdio mode)
For use with MCP clients like Claude Desktop:
```bash
cd geo_mcp_server
python main.py --mode stdio
```
### HTTP Server (localhost:8000)
For HTTP API access:
```bash
# Option 1: Using the main script
cd geo_mcp_server
python main.py --mode http --host localhost --port 8000
# Option 2: Using the convenience script
python run_server.py
```
### HTTP API Endpoints
Once the HTTP server is running on localhost:8000, you can access:
- **Root**: `GET /` - Server status
- **Health Check**: `GET /health` - Health check endpoint
- **List Tools**: `GET /tools` - List all available tools
- **Call Tool**: `POST /tools/call` - Execute a tool with arguments
- **API Documentation**: `GET /docs` - Interactive API documentation (Swagger UI)
### Example HTTP API Usage
```bash
# List available tools
curl http://localhost:8000/tools
# Search GEO Profiles
curl -X POST http://localhost:8000/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "search_geo_profiles",
"arguments": {
"term": "cancer",
"retmax": 5
}
}'
# Search GEO Datasets
curl -X POST http://localhost:8000/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "search_geo_datasets",
"arguments": {
"term": "breast cancer",
"retmax": 10
}
}'
```
## Available Tools
This MCP server provides access to all major GEO databases through the following tools:
### Search Tools
- **`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:** `/Users/matthiasflo/Documents/2025/GEO_MCP/geo_mcp_server/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.
Raw data
{
"_id": null,
"home_page": null,
"name": "geo-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "bioinformatics, e-utils, gene-expression, geo, mcp, ncbi",
"author": null,
"author_email": "MCPmed Contributors <matthias.flotho@ccb.uni-saarland.de>",
"download_url": "https://files.pythonhosted.org/packages/da/c3/0566b790e3e607db74fcc7018487c498fac9ec54b2ef87d5b75ea4d1323e/geo_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# Gene Expression Omnibus (GEO) MCP\n\n<div align=\"center\">\n <img src=\"https://www.ncbi.nlm.nih.gov/geo/img/geo_main.gif\" alt=\"GEO Logo\" width=\"200\"/>\n <br/>\n <em>Gene Expression Omnibus (GEO) - A public functional genomics data repository</em>\n</div>\n\n[](https://pypi.org/project/geo-bio-mcp/)\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://modelcontextprotocol.io/)\n[](https://www.ncbi.nlm.nih.gov/geo/)\n\n> \u26a0\ufe0f **Development Warning** \u26a0\ufe0f\n> \n> **This project is currently in active development and is not yet production-ready.**\n> \n> - The MCP stdio server is functional but may have bugs or incomplete features\n> - The HTTP server is in early development phase and has **not been properly tested**\n> - API endpoints and functionality may change without notice\n> - Use at your own risk and report any issues you encounter\n> \n> We recommend testing thoroughly in a development environment before using in production.\n\nA Model Context Protocol (MCP) server for accessing [GEO (Gene Expression Omnibus)](https://www.ncbi.nlm.nih.gov/geo/) data through NCBI E-Utils API.\nThe tool will enable you to search for GEO datasets, series, samples, platforms, and profiles for your LLM.\nTested with Claude Desktop, chatGPT has no out of the box support for this tool yet.\nClaude will automatically use the tools if it fits the context.\n\n## Quick Install (pip)\n\ninstall from pip\n```bash\npip install geo-bio-mcp\n```\ninstall from source\n```bash\n# Clone the repo (if not already)\ngit clone <repo-url>\ncd GEO_MCP\npip install -e .\n```\n\n## Configuration\n\nRun init to create a config file\n```bash\ngeo-bio-mcp --init\n```\n\nThis will create a config file at `~/.geo-bio-mcp/config.json` (auto-created on first run if missing).\nThis file will contain the following:\n```json\n{\n \"base_url\": \"https://eutils.ncbi.nlm.nih.gov/entrez/eutils\",\n \"email\": \"your_email@example.com\",\n \"api_key\": \"YOUR_API_KEY\"\n}\n```\n\nIt will also print out a configuration template for your claude desktop configuration file.\n\n- `email` is required by NCBI.\n- `api_key` is optional but recommended for higher rate limits ([get one here](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)).\n\n## Running the Server\n\n- **MCP stdio mode:**\n ```bash\n geo-bio-mcp\n ```\n- **HTTP mode:**\n ```bash\n geo-bio-mcp --http --port 8001\n ```\n\n## Claude Desktop Integration\n\n### Common Issue: `spawn geo-bio-mcp ENOENT`\n\nThis error means Claude Desktop cannot find the `geo-bio-mcp` command. This is usually a PATH issue.\n\n### Solution\n1. **Find the full path to the executable:**\n ```bash\n which geo-bio-mcp\n ```\n Example output: `/Users/youruser/miniforge3/bin/geo-bio-mcp`\n\n2. **Update your Claude config:**\n Instead of just `\"geo-bio-mcp\"`, use the full path:\n ```json\n {\n \"mcpServers\": {\n \"geo-mcp\": {\n \"command\": \"/Users/youruser/miniforge3/bin/geo-bio-mcp\",\n \"env\": {\n \"CONFIG_PATH\": \"/Users/youruser/.geo-mcp/config.json\"\n }\n }\n }\n }\n ```\n\n3. **(Optional) Use a Conda Environment:**\n - Activate your conda env and run `which geo-bio-mcp` to get the correct path.\n - Use that path in your Claude config as above.\n\n4. **Restart Claude Desktop** after updating the config.\n\n---\n\n## Troubleshooting\n- If you see `command not found: geo-bio-mcp`, make sure you installed with the correct Python/conda environment and that its `bin` directory is in your PATH.\n- If the config file is missing, it will be auto-created on first run, or you can copy the template from `geo_mcp_server/config_template.json`.\n\n---\n\n## Usage\n\n### MCP Server (stdio mode)\nFor use with MCP clients like Claude Desktop:\n\n```bash\ncd geo_mcp_server\npython main.py --mode stdio\n```\n\n### HTTP Server (localhost:8000)\nFor HTTP API access:\n\n```bash\n# Option 1: Using the main script\ncd geo_mcp_server\npython main.py --mode http --host localhost --port 8000\n\n# Option 2: Using the convenience script\npython run_server.py\n```\n\n### HTTP API Endpoints\n\nOnce the HTTP server is running on localhost:8000, you can access:\n\n- **Root**: `GET /` - Server status\n- **Health Check**: `GET /health` - Health check endpoint\n- **List Tools**: `GET /tools` - List all available tools\n- **Call Tool**: `POST /tools/call` - Execute a tool with arguments\n- **API Documentation**: `GET /docs` - Interactive API documentation (Swagger UI)\n\n### Example HTTP API Usage\n\n```bash\n# List available tools\ncurl http://localhost:8000/tools\n\n# Search GEO Profiles\ncurl -X POST http://localhost:8000/tools/call \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"search_geo_profiles\",\n \"arguments\": {\n \"term\": \"cancer\",\n \"retmax\": 5\n }\n }'\n\n# Search GEO Datasets\ncurl -X POST http://localhost:8000/tools/call \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"search_geo_datasets\", \n \"arguments\": {\n \"term\": \"breast cancer\",\n \"retmax\": 10\n }\n }'\n```\n\n## Available Tools\n\nThis MCP server provides access to all major GEO databases through the following tools:\n\n### Search Tools\n\n- **`search_geo_profiles`** - Search gene expression profiles across different biological contexts\n - *Example searches*: \"cancer\", \"breast cancer\", \"p53\", \"apoptosis\"\n \n- **`search_geo_datasets`** - Search curated gene expression datasets\n - *Example searches*: \"diabetes\", \"Alzheimer's disease\", \"drug response\", \"tissue specific\"\n \n- **`search_geo_series`** - Search original submitter-supplied gene expression series\n - *Example searches*: \"GSE12345\", \"microarray\", \"RNA-seq\", \"time course\"\n \n- **`search_geo_samples`** - Search individual gene expression samples\n - *Example searches*: \"GSM123456\", \"human\", \"mouse\", \"tumor\", \"normal\"\n \n- **`search_geo_platforms`** - Search microarray platform definitions\n - *Example searches*: \"Affymetrix\", \"Illumina\", \"Agilent\", \"GPL96\"\n\n### Search Parameters\n\nEach tool accepts:\n- **`term`** (required): Search term or query string\n- **`retmax`** (optional, default: 20): Maximum number of results to return\n\n### Example usage\nFor now just chat with claude desktop and it will use the tools automatically if it fits the context.\n\n**User:** find a small brain dataset \n\n**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. \n\n**Assistant (system):** *search_geo_datasets* \n\n**Assistant:** I found a brain-related dataset for you:\n\n- **Dataset:** GSE290848 \n- **Title:** Maternal Stress Triggers Early-Life Eczema via Fetal Mast Cell Reprogramming [10x Genomics Multiome ATAC + Gene Expression] \n- **Species:** Mouse (*Mus musculus*) \n- **Samples:** 8 \n- **Data type:** ATAC-seq & gene expression (10x Genomics Multiome) \n- **Publication date:** 21 Jun 2025 \n\nThis small dataset explores how prenatal stress affects neuro-immune circuits and mast-cell development. \n\nWould you like me to download this dataset or search for others?\n\n---\n\n**User:** download GSE290848 \n\n**Assistant:** I'll download the GSE290848 dataset for you. \n\n**Assistant (system):** *download_geo_data* \n\n**Assistant:** Download complete. \n\n**Downloaded files**\n\n- `GSE290848_family.soft.gz` \u2014 series, platform & sample info \n- `GSE290848_metadata.xml` \u2014 detailed study metadata \n\n**Location:** `/Users/matthiasflo/Documents/2025/GEO_MCP/geo_mcp_server/downloads/gse/GSE290848` \n**Total size:** 0.01 MB \n\nThe dataset is ready for analysis. Let me know if you\u2019d like to explore it further.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol (MCP) server for accessing GEO (Gene Expression Omnibus) data through NCBI E-Utils API",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/MCPmed/geomcp/issues",
"Documentation": "https://github.com/MCPmed/geomcp#readme",
"Homepage": "https://github.com/MCPmed/geomcp",
"Repository": "https://github.com/MCPmed/geomcp"
},
"split_keywords": [
"bioinformatics",
" e-utils",
" gene-expression",
" geo",
" mcp",
" ncbi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "24b71ace82df4b46d012bf5da1d3e61d3ac31065c3bc98b5656eec2bbe0118e8",
"md5": "a7626b882f2dd2c78b8452d82bcae5b8",
"sha256": "31ea7be8c0e9380ebc866d9e766d9e0e2dfda59aadff7823306a71be8ec9414a"
},
"downloads": -1,
"filename": "geo_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7626b882f2dd2c78b8452d82bcae5b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 21567,
"upload_time": "2025-07-30T11:49:53",
"upload_time_iso_8601": "2025-07-30T11:49:53.940288Z",
"url": "https://files.pythonhosted.org/packages/24/b7/1ace82df4b46d012bf5da1d3e61d3ac31065c3bc98b5656eec2bbe0118e8/geo_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dac30566b790e3e607db74fcc7018487c498fac9ec54b2ef87d5b75ea4d1323e",
"md5": "38c2dbf321020a7c08b18345a5b9cdc6",
"sha256": "6a51da66a330b3ec98b970ce557b7b88e4d0d9b7ece2b4dec8ab154f24fd4cc8"
},
"downloads": -1,
"filename": "geo_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "38c2dbf321020a7c08b18345a5b9cdc6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26306,
"upload_time": "2025-07-30T11:49:55",
"upload_time_iso_8601": "2025-07-30T11:49:55.605019Z",
"url": "https://files.pythonhosted.org/packages/da/c3/0566b790e3e607db74fcc7018487c498fac9ec54b2ef87d5b75ea4d1323e/geo_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 11:49:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MCPmed",
"github_project": "geomcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "geo-mcp"
}
