Skip to main content
Glama
millimap-mcp

millimap-mcp

Official
by milliomics

millimap-mcp

MCP (Model Context Protocol) server that lets Claude Desktop read the active MilliMap session — its dataset, clusters, cell-type annotations, marker genes, regions of interest — and drive analyses inside the viewer from chat.

How it works

┌──────────────────┐       writes        ┌──────────────────────────┐
│  MilliMap        │  ──────────────▶    │  ~/.millimap/            │
│  (desktop app)   │     every 3s        │  mcp_session.json        │
└──────────────────┘                     └──────────────────────────┘
                                                    │ reads
                                                    ▼
                                         ┌──────────────────────────┐
┌──────────────────┐     stdio MCP       │  millimap-mcp            │
│  Claude Desktop  │  ◀───────────────▶  │  (this package)          │
└──────────────────┘                     └──────────────────────────┘

MilliMap writes a snapshot of its current session to ~/.millimap/mcp_session.json every few seconds. This MCP server is launched by Claude Desktop as a stdio subprocess; it reads the snapshot and exposes it to Claude as MCP resources and tools.

Related MCP server: TradingView MCP Jackson

Prerequisites

Install — into your existing MilliMap environment

Important: install millimap-mcp into the same Python environment you use to run MilliMap. That way the resulting millimap-mcp script lands in that env's bin/ (or Scripts\ on Windows), and Claude Desktop finds it automatically when you activate the env.

# 1. Activate the MilliMap env FIRST — this is the step people miss.
conda activate millimap

# 2. Clone this repo somewhere convenient.
git clone https://github.com/milliomics/millimap-mcp.git
cd millimap-mcp

# 3. Install into the activated env.
pip install -e .

If you set up MilliMap with pip (no conda)

Use the same Python you use to launch MilliMap. The safest invocation is to spell out the interpreter explicitly:

git clone https://github.com/milliomics/millimap-mcp.git
cd millimap-mcp

# Replace this with the python you use for MilliMap:
/path/to/your/python -m pip install -e .

# e.g.:
# /usr/local/bin/python3.11 -m pip install -e .
# or:
# /Users/you/venvs/millimap/bin/python -m pip install -e .

Verify the install

After install, the millimap-mcp script should be on your PATH (when the env is activated):

which millimap-mcp           # macOS / Linux
where millimap-mcp           # Windows

You should see a path under your MilliMap env, e.g.:

  • conda: /Users/<you>/anaconda3/envs/millimap/bin/millimap-mcp

  • venv: /Users/<you>/venvs/millimap/bin/millimap-mcp

  • Windows conda: C:\Users\<you>\anaconda3\envs\millimap\Scripts\millimap-mcp.exe

Keep that path handy — you'll paste it into Claude Desktop's config in the next step (or just use the bare name millimap-mcp if Claude Desktop sees the same PATH you do).

Wire it up to Claude Desktop

Open Claude Desktop's config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Create the file if it doesn't exist. Add (merge into any existing mcpServers object):

{
  "mcpServers": {
    "millimap": {
      "command": "millimap-mcp"
    }
  }
}

Use an absolute path if millimap-mcp isn't on Claude Desktop's PATH

Claude Desktop launches subprocesses with its own PATH, which may not include your conda env's bin/. If you get "command not found" / "spawn ENOENT" after restarting Claude, swap the bare command for the absolute path you got from which millimap-mcp above:

{
  "mcpServers": {
    "millimap": {
      "command": "/Users/<you>/anaconda3/envs/millimap/bin/millimap-mcp"
    }
  }
}

On Windows, double-escape backslashes (JSON requires it):

{
  "mcpServers": {
    "millimap": {
      "command": "C:\\Users\\<you>\\anaconda3\\envs\\millimap\\Scripts\\millimap-mcp.exe"
    }
  }
}

Then fully quit + relaunch Claude Desktop (the window-close X is not enough — quit from the menu bar / system tray).

In Claude Desktop's tools menu (plug icon in the message composer) you should now see millimap. Toggle it on.

What Claude can see

Resources (read-only context):

  • millimap://session — dataset name, cell/gene counts, assay, cluster column

  • millimap://clusters — cluster IDs and sizes

  • millimap://annotations — cluster → cell-type labels set by the scientist

  • millimap://markers — top marker genes per cluster

  • millimap://rois — regions of interest saved in the session

  • millimap://analysis_cards — workspace result cards (summaries only — use get_analysis_card for the full payload)

Read tools (read the snapshot, no side effects):

  • get_cluster_markers(cluster_id, top_n) — markers for one cluster

  • genes_for_cell_type(cell_type) — "what genes mark T cells?"

  • search_genes(query, limit) — find which cluster a gene marks

  • list_rois() — enumerate saved ROIs

  • list_analysis_cards() — workspace result cards (summaries)

  • get_analysis_card(card_id, max_rows) — full payload of one card including its DataFrame

Write tools (drive MilliMap's analysis library + UI):

  • run_clustering(resolution, n_neighbors) — re-cluster the dataset

  • find_markers(groupby, method) — run rank_genes_groups

  • annotate_cluster(cluster_id, label) — assign a cell-type label

  • score_gene_signature(genes, score_name) — score a gene set across cells

  • apply_qc_filter(min_genes, max_genes, min_counts, max_mito_pct) — QC filter

  • run_millimap_tool(tool_name, tool_args_json) — escape hatch for any of MilliMap's 30+ analysis tools (DE, GO enrichment, neighborhood enrichment, co-occurrence, Ripley, doublet detection, dotplot/heatmap/violin, etc.)

Write tools require MilliMap to be running with a dataset loaded. They POST to a local HTTP endpoint (127.0.0.1, ephemeral port) served by the viewer; the port is discovered via ~/.millimap/mcp_control.json.

Available Tools

12 tools
annotate_clusterA

Set a cell-type annotation on a cluster in the running MilliMap session.

The label appears in MilliMap's annotation panel and is written back to the session snapshot — use this when you've figured out what a cluster is.

Args: cluster_id: Cluster identifier as shown in MilliMap (e.g. "Cluster 3", "1"). label: Cell-type name (e.g. "CD8+ T cell", "fibroblast", "doublet").

Inputs: cluster_id (required), label (required). Returns: result

apply_qc_filterA

Apply QC filters to the active dataset in MilliMap.

Replaces the active adata with the filtered subset and re-renders. The original can be restored via the in-app QC controls.

Inputs: min_genes, max_genes, min_counts, max_mito_pct. Returns: result

find_markersA

Run rank_genes_groups in MilliMap to find marker genes per cluster.

After this completes, the MilliMap snapshot refreshes with the top markers per cluster — subsequent calls to get_cluster_markers or genes_for_cell_type will see them.

Args: groupby: obs column to group by. Default 'clusters'. method: 'wilcoxon' (default), 't-test', or 'logreg'.

Inputs: groupby, method. Returns: result

genes_for_cell_typeA

Find which clusters are annotated as a given cell type, with their markers.

Use this when the user asks things like "what genes are for T cells" — we find every cluster labelled with that cell type and return their marker genes.

Inputs: cell_type (required). Returns: result

get_analysis_cardA

Fetch the full payload of one analysis result card, including its underlying DataFrame (up to max_rows rows, default 50).

Use this to inspect the actual numbers behind a card — e.g. the differential expression table, spatial autocorrelation p-values, neighborhood enrichment z-scores — so you can reason over the result.

Args: card_id: The id field from list_analysis_cards (a hex token). max_rows: Max rows of the DataFrame to include (1–500, default 50).

Inputs: card_id (required), max_rows. Returns: result

get_cluster_markersB

Return top marker genes for a specific cluster.

Args: cluster_id: Cluster identifier as a string (e.g., "0", "1", "CD8_T"). top_n: Number of top markers to return (default 10, max 15).

Inputs: cluster_id (required), top_n. Returns: result

list_analysis_cardsA

List the analysis result cards visible in MilliMap's workspace sidebar.

Same data as the millimap://analysis_cards resource — returns an array of summaries. Use get_analysis_card to load the full payload for a specific card.

Inputs: no named parameters. Returns: result

list_roisA

List all ROIs saved in the current MilliMap session.

Inputs: no named parameters. Returns: result

run_clusteringA

Run MilliMap's clustering pipeline on the active dataset.

Runs PCA → neighbors (n_neighbors) → Leiden (resolution) → UMAP using Scanpy and updates the 3D view in MilliMap with the new cluster labels.

Args: resolution: Leiden resolution (higher = more clusters). Default 0.5. n_neighbors: k for the neighbors graph. Default 15.

Inputs: resolution, n_neighbors. Returns: result

run_millimap_toolA

Escape hatch — run any of MilliMap's 30+ analysis tools by name.

Use when a workflow needs a tool not individually exposed above.

Examples of tool_name: run_deg_clusters, run_deg_roi, run_go_enrichment, find_spatially_variable_genes, run_neighborhood_enrichment, run_co_occurrence, run_centrality_scores, run_interaction_matrix, run_ripley, run_ligrec, run_pca, run_louvain, run_diffmap, run_draw_graph, run_paga, run_dpt, run_embedding_density, run_doublet_detection, normalize_data, find_highly_variable_genes, score_cell_cycle, create_dotplot, create_heatmap, create_stacked_violin, annotate_clusters.

Args: tool_name: Exact tool name from the list above. tool_args_json: JSON string of arguments, e.g. '{"group_a": "1", "group_b": "2"}'.

Inputs: tool_name (required), tool_args_json. Returns: result

score_gene_signatureA

Score a gene signature across all cells and add it as an obs column.

Use this to apply a published signature (e.g. exhausted T cell markers, EMT genes) to the dataset. The score becomes a colorable field in MilliMap.

Args: genes: List of gene symbols to score together. score_name: Name for the new obs column (default 'mcp_score').

Inputs: genes (required), score_name. Returns: result

search_genesC

Case-insensitive search across marker genes. Returns matching genes and which cluster they mark.

Inputs: query (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes, but the set of marker-related tools (find_markers, get_cluster_markers, genes_for_cell_type, search_genes) may cause some confusion as they all deal with marker genes, though descriptions clarify their specific roles.

    Naming Consistency4/5

    Tool names follow a verb_noun pattern in snake_case, which is consistent. However, 'genes_for_cell_type' deviates by starting with a noun instead of a verb, making it a minor inconsistency.

    Tool Count5/5

    With 12 tools covering clustering, annotation, marker retrieval, QC, and an escape hatch, the count is well-scoped for a single-cell analysis MCP server—each tool earns its place.

    Completeness3/5

    The tool surface covers core clustering and annotation but misses direct tools for data loading, normalization, or highly variable gene selection—essential preprocessing steps. The escape hatch partially fills these gaps but reliance on it for key operations indicates notable gaps.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to control and read from the TradingView Desktop app, providing automated morning briefs, chart analysis, Pine Script development, and replay mode.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude Desktop to view and interact with the currently open QGIS project, including layers, styling, selections, Processing algorithms, attribute editing, and geocoding, all running locally.
      10
      GPL 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables visualizing GeoJSON data on an interactive map directly in Claude Desktop, allowing users to request maps of information found or generated.
      MIT