Skip to content

OmicVerse MCP Quick Start

This is the shortest path to a working OmicVerse MCP setup.

Prerequisites

Before you start, make sure you have:

  • Claude Code or another MCP client
  • Python >=3.10
  • either a local .h5ad file or willingness to use a built-in dataset

Install

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

Start the Server

Common phase selections

# Core only
python -m omicverse.mcp --phase P0

# Default: core + analysis/visualization
python -m omicverse.mcp --phase P0+P0.5

# Full rollout including P2 class-backed tools
python -m omicverse.mcp --phase P0+P0.5+P2

Default stdio mode

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

Local HTTP mode

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

Use stdio by default. Use local HTTP when you want a separately managed MCP process or easier server-side debugging.

If you need advanced class-backed tools, use the same startup pattern with --phase P0+P0.5+P2.

Claude Code Setup

Option A: Claude launches OmicVerse directly

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

For P2:

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

Option B: Claude connects to your local HTTP MCP

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

More deployment patterns are in Clients & Deployment.

First Commands to Try

Load a built-in dataset

Load the built-in pbmc3k dataset

Or load a file:

Load the pbmc3k.h5ad file

Inspect the dataset

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

Run a standard preprocessing workflow

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

Plot and summarize

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

What the Server Is Actually Doing

Under the hood, OmicVerse MCP is calling tools such as:

  1. ov.datasets.pbmc3k or 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

The dataset stays server-side and is referenced by adata_id.

Minimal JSON Shape You Will See

Loading data typically returns an object reference like:

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

You normally do not need to manage the adata_id manually because Claude tracks it across turns.

One Short Walkthrough

  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

Next Pages