Cellxgene MCP

CELLxGEN人口普查MCP服务器

一种模型上下文协议（MCP）服务器，提供对 CZ CELLxGENE 发现人口普查 -单细胞RNA测序数据的全面收集。

特性

• 🧬 查询单元格元数据：探索细胞类型、组织、疾病和其他细胞注释
• 🧫 查询基因元数据：在人口普查中搜索基因及其注释
• 📊 数据切片摘要：在不下载完整矩阵的情况下获取数据切片的概览统计信息
• 🔍 灵活的过滤：使用pandas风格的查询来过滤单元格和基因
• 🌍 多生物支持：从人和鼠标访问数据
• ⚡ 内存效率高：内置限制，防止内存过载

安装

先决条件

• Python 3.10+
• 紫外线 （推荐）或pip

使用紫外线进行安装（推荐）

# Clone the repository
git clone 
cd cellxgene-mcp

# Install dependencies
uv sync

# Install the package in development mode
uv pip install -e .

使用pip安装

pip install -r requirements.txt
pip install -e .

快速开始

运行MCP服务器

标准传输（适用于MCP客户端）

uv run cellxgene-mcp

HTTP传输（用于web访问）

uv run server --host 0.0.0.0 --port 3001

SSE 运输

uv run sse --host 0.0.0.0 --port 3001

MCP客户端配置

将此添加到MCP客户端配置中：

对于stdio传输：

{
  "mcpServers": {
    "cellxgene-mcp": {
      "command": "uv",
      "args": ["run", "cellxgene-mcp"]
    }
  }
}

对于HTTP传输：

{
  "mcpServers": {
    "cellxgene-mcp": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

可用工具

cellxgene_get_census_info

获取有关可用人口普查版本和支持的生物体的信息。

退货：

• 可用的人口普查版本
• 最新稳定版本
• 支持的生物体
• 数据类型

cellxgene_get_obs_metadata

从人口普查中查询单元格（观测）元数据。

参数：

• organism （str）：“智人”或“肌肉鼠”（默认：“智人类”）
• value_filter （str，可选）：Pandas样式的过滤表达式
• column_names （str，可选）：返回以逗号分隔的列列表
• limit （int）：返回的最大行数（默认值：1000）

过滤器示例：

cell_type == 'T cell'
tissue == 'lung' and disease == 'COVID-19'
sex == 'female' and cell_type in ['T cell', 'B cell']

cellxgene_get_var_metadata

从人口普查中查询基因（变量）元数据。

参数：

• organism （str）：“智人”或“肌肉鼠”（默认：“智人类”）
• value_filter （str，可选）：Pandas样式的过滤表达式
• column_names （str，可选）：返回以逗号分隔的列列表
• limit （int）：返回的最大行数（默认值：1000）

过滤器示例：

feature_name in ['CD4', 'CD8A', 'CD3E']
feature_id == 'ENSG00000010610'

cellxgene_get_data_slice

从人口普查中获取数据片段的摘要。

参数：

• organism （str）：“智人”或“小肌肉”
• obs_value_filter （str，可选）：单元格筛选器
• var_value_filter （str，可选）：筛选基因
• obs_column_names （str，可选）：要包含的单元格元数据列
• var_column_names （str，可选）：要包含的基因元数据列
• max_cells （int）：最大单元格数（默认值：10000）
• max_genes （int）：最大基因数（默认值：2000）

退货：

• 细胞和基因的数量
• 元数据示例
• 列信息
• 查询信息

可用资源

resource://cellxgene_census-info

关于CELLxGEN人口普查数据库的全面信息，包括：

• 可用生物体
• 关键元数据字段
• 常见查询模式
• 使用指南

数据模式

单元格（观察）元数据字段

• cell_type：单元格类型注释
• tissue：来源组织
• disease：疾病状态
• sex：生物性别
• organism：物种
• assay：使用的测序分析
• suspension_type：细胞或细胞核
• ethnicity：自我报告的种族（仅限人类）
• development_stage：发展阶段

基因（可变）元数据字段

• feature_id：Ensembl基因ID
• feature_name：基因符号
• feature_length：基因长度

查询示例

探索肺组织中的T细胞

# Get T cells from lung tissue
obs_data = await get_obs_metadata(
    organism="Homo sapiens",
    value_filter="cell_type == 'T cell' and tissue == 'lung'",
    column_names="cell_type,tissue,disease,sex,assay"
)

查找新冠肺炎相关数据

# Get cells from COVID-19 studies
obs_data = await get_obs_metadata(
    organism="Homo sapiens", 
    value_filter="disease == 'COVID-19'",
    column_names="cell_type,tissue,disease,assay"
)

搜索特定基因

# Get information about immune genes
var_data = await get_var_metadata(
    organism="Homo sapiens",
    value_filter="feature_name in ['CD4', 'CD8A', 'CD3E', 'IL2']",
    column_names="feature_id,feature_name,feature_length"
)

获取数据切片摘要

# Get summary of T cell data slice
data_summary = await get_data_slice(
    organism="Homo sapiens",
    obs_value_filter="cell_type == 'T cell'",
    var_value_filter="feature_name in ['CD4', 'CD8A', 'CD3E']",
    max_cells=5000,
    max_genes=100
)

发展

项目结构

cellxgene-mcp/
├── src/cellxgene_mcp/
│   ├── __init__.py
│   └── server.py
├── test/
├── mcp-config*.json
├── pyproject.toml
└── README.md

运行测试

uv run pytest test/

代码格式化

uv run ruff format .
uv run ruff check .

局限性

• 内存限制：内置限制可防止下载超大数据集
• 查询复杂性：非常复杂的查询可能很慢
• 速率限制：遵守人口普查服务费率限制
• 网络依赖性：需要互联网连接才能访问人口普查数据

相关项目

• CELLxGEN普查
• FastMCP
• 模型上下文协议

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

• GitHub存储库上的文件问题
• 检查 CELLxGEN人口普查文件 数据问题
• 查看 MCP规范 关于协议问题