OmicVerse MCP 快速开始

OmicVerse MCP 快速开始#

这是搭建 OmicVerse MCP 的最短路径。

前提条件#

开始之前，请确认您已准备好：

  • Claude Code 或其他 MCP 客户端

  • Python >=3.10

  • 本地 .h5ad 文件，或愿意使用内置数据集

安装#

pip install omicverse[mcp]
python -m omicverse.mcp --version

启动服务器#

常用阶段选项#

# 仅核心
python -m omicverse.mcp --phase P0

# 默认：核心 + 分析/可视化
python -m omicverse.mcp --phase P0+P0.5

# 完整部署，包含 P2 基于类的工具
python -m omicverse.mcp --phase P0+P0.5+P2

默认 stdio 模式#

python -m omicverse.mcp --phase P0+P0.5

本地 HTTP 模式#

NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/mpl \
python -m omicverse.mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8765 \
  --http-path /mcp \
  --phase P0+P0.5

默认使用 stdio。当您希望独立管理 MCP 进程或进行服务器端调试时，使用本地 HTTP。

如需高级的基于类的工具，使用相同的启动方式，但加上 --phase P0+P0.5+P2。

Claude Code 配置#

选项 A：Claude 直接启动 OmicVerse#

{
  "mcpServers": {
    "omicverse": {
      "command": "python",
      "args": ["-m", "omicverse.mcp", "--phase", "P0+P0.5"]
    }
  }
}

使用 P2：

{
  "mcpServers": {
    "omicverse": {
      "command": "python",
      "args": ["-m", "omicverse.mcp", "--phase", "P0+P0.5+P2"]
    }
  }
}

选项 B：Claude 连接到您的本地 HTTP MCP#

{
  "mcpServers": {
    "omicverse": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

更多部署模式请参阅客户端与部署。

首先尝试的命令#

加载内置数据集#

Load the built-in pbmc3k dataset

或加载文件：

Load the pbmc3k.h5ad file

检查数据集#

Describe the current adata
What is the first gene in var?
Does CD3D exist in var_names?
Inspect adata.uns
Inspect adata.obsm

运行标准预处理工作流程#

Run QC, scale, PCA with 50 components, build neighbors, compute UMAP, and run Leiden clustering at resolution 1.0

绘图与汇总#

Plot the UMAP colored by leiden
Find marker genes for each Leiden cluster
Plot a marker gene dotplot

服务器实际在做什么#

在底层，OmicVerse MCP 调用如下工具：

  1. ov.datasets.pbmc3k 或 ov.utils.read

  2. ov.pp.qc

  3. ov.pp.scale

  4. ov.pp.pca

  5. ov.pp.neighbors

  6. ov.pp.umap

  7. ov.pp.leiden

数据集保留在服务器端，通过 adata_id 引用。

您将看到的最简 JSON 格式#

加载数据通常返回如下对象引用：

{
  "ok": true,
  "tool_name": "ov.utils.read",
  "outputs": [
    {
      "type": "object_ref",
      "ref_type": "adata",
      "ref_id": "adata_a1b2c3d4e5f6"
    }
  ]
}

通常您不需要手动管理 adata_id，因为 Claude 会在对话中自动追踪它。

一个简短的演练#

  1. Load the built-in pbmc3k dataset

  2. Describe the current adata

  3. Run QC, scale, PCA with 50 components, build neighbors, compute UMAP, and run Leiden clustering

  4. Plot the UMAP colored by leiden

  5. Find marker genes for each Leiden cluster and show the top 5

后续页面#

目录