millimap-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@millimap-mcp list the cell-type annotations in my dataset"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
MilliMap installed and runnable — see milliomics/MilliMap.
Claude Desktop — download from anthropic.com.
Python 3.10+ with
pip.
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.
If you set up MilliMap with conda (the recommended path)
# 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 # WindowsYou should see a path under your MilliMap env, e.g.:
conda:
/Users/<you>/anaconda3/envs/millimap/bin/millimap-mcpvenv:
/Users/<you>/venvs/millimap/bin/millimap-mcpWindows 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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 columnmillimap://clusters— cluster IDs and sizesmillimap://annotations— cluster → cell-type labels set by the scientistmillimap://markers— top marker genes per clustermillimap://rois— regions of interest saved in the sessionmillimap://analysis_cards— workspace result cards (summaries only — useget_analysis_cardfor the full payload)
Read tools (read the snapshot, no side effects):
get_cluster_markers(cluster_id, top_n)— markers for one clustergenes_for_cell_type(cell_type)— "what genes mark T cells?"search_genes(query, limit)— find which cluster a gene markslist_rois()— enumerate saved ROIslist_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 datasetfind_markers(groupby, method)— runrank_genes_groupsannotate_cluster(cluster_id, label)— assign a cell-type labelscore_gene_signature(genes, score_name)— score a gene set across cellsapply_qc_filter(min_genes, max_genes, min_counts, max_mito_pct)— QC filterrun_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 toolsannotate_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
Scored across 12 tools
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.
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.
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.
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
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Read, edit, publish, and preview your pepita websites from Claude.
Give Claude only the Google Drive files you choose. Every action logged.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to control the local desktop via screenshot, mouse, keyboard, and clipboard operations.MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to control and read from the TradingView Desktop app, providing automated morning briefs, chart analysis, Pine Script development, and replay mode.-
- AlicenseAqualityCmaintenanceEnables 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.10GPL 2.0
- AlicenseNot gradedqualityCmaintenanceEnables visualizing GeoJSON data on an interactive map directly in Claude Desktop, allowing users to request maps of information found or generated.MIT