lineageverse-mcp
Provides optimization solver capabilities for exact-ILP tree reconstruction methods.
Provides access to example single-cell lineage tracing datasets for loading via load_example_dataset.
Click 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., "@lineageverse-mcp Load yang22 example dataset and plot the tree"
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.
lineageverse-mcp
An MCP server for single-cell lineage tracing
analysis. It wraps the scverse-style lineage stack —
Cassiopeia (reconstruction),
pycea (plotting + heritability), and
treedata (the shared TreeData object) — behind a small
set of MCP tools so an assistant can drive analyses conversationally:
"Reconstruct a lineage tree from this character-matrix CSV."
"Plot the tree next to its character matrix."
"Which genes are most heritable on this tree (Moran's I)?"
Install
Requires Python ≥ 3.12. Cassiopeia builds Cython extensions, so you need a C compiler
(Xcode Command Line Tools on macOS, build-essential on Linux).
# 1. The MCP server + its PyPI dependencies (treedata, pycea, scanpy, anndata, mcp, ...)
pip install lineageverse-mcp # from PyPI once published
# ...or from a checkout: pip install -e .
# 2. Cassiopeia v3 (the functional TreeData API). Not yet on PyPI — install from GitHub:
pip install "cassiopeia-lineage @ git+https://github.com/YosefLab/Cassiopeia.git@3.0.0"Optional extras:
# Interactive web viewer; install only if you want launch_viewer:
pip install cellxlineage
# Exact-ILP reconstruction (methods "ilp"/"hybrid") additionally needs a licensed Gurobi:
pip install gurobipyIf cellxlineage cannot go in the same environment (its dependency pins conflict with your
stack), install it separately and point the server at it with
LINEAGEVERSE_CELLXLINEAGE_BIN=/path/to/cellxlineage.
Related MCP server: ChatSpatial
Run
lineageverse-mcp # STDIO transport (what MCP clients launch)
mcp dev src/lineageverse_mcp/server.py # MCP Inspector for interactive testingClaude Code
claude mcp add lineageverse -- lineageverse-mcpClaude Desktop
Edit the config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
%APPDATA%\Claude\claude_desktop_config.json on Windows) and point it at the installed
executable:
{
"mcpServers": {
"lineageverse": { "command": "/path/to/your/env/bin/lineageverse-mcp" }
}
}If installed in a conda env, use conda run instead:
{
"mcpServers": {
"lineageverse": {
"command": "conda",
"args": ["run", "--no-capture-output", "-n", "YOUR_ENV", "lineageverse-mcp"]
}
}
}Running the server on a remote host (e.g. an HPC cluster where the data lives): Desktop
is macOS/Windows only, so launch the server over SSH. Set command to ssh and
args to ["-T", "user@host", "/abs/path/to/env/bin/lineageverse-mcp"]. SSH must be
non-interactive (key-based auth) and must not print anything to stdout (call the binary by
absolute path so login rc files aren't sourced), or the JSON-RPC stream will be corrupted.
Tools
Tool | Purpose |
| Load a |
| Load a built-in pycea example dataset ( |
| Inspect loaded datasets. |
| Build a tree ( |
| Pairwise distance map (for |
| Rank features by Moran's I / Geary's C on a tree. |
| Characterize a tree. |
| Robinson-Foulds / triplets between two trees. |
| Render a tree (+ character-matrix / annotation heatmap). |
| Generate ground-truth trees and character matrices. |
| Persist results. |
| Open the interactive cellxlineage web viewer on a dataset (optional). |
Design
Datasets are held in an in-memory session store keyed by dataset_id and mutated in place
across calls (matching the AnnData/TreeData idiom); save_dataset persists to
<workspace>/<id>.h5td. The workspace defaults to ~/.lineageverse
(override with LINEAGEVERSE_WORKSPACE). Each tool module registers itself with the FastMCP
app via register(mcp), so adding a capability is just adding a function.
To try it end-to-end without your own data, ask for load_example_dataset (downloads a small
.h5td from Zenodo), then plot_tree and compute_heritability on it.
Development
pip install -e ".[test]"
pytestHeavy ilp reconstructions can be slow; on a shared cluster, run those on a compute node.
Available Tools
18 toolscalculate_parsimonyB
Compute the total parsimony (number of mutations) of a tree given its characters.
Inputs: tree_key (required), dataset_id (required), characters_key. Returns: result
compare_treesB
Compare two trees in the same dataset.
Metrics:
"rf": Robinson-Foulds distance (also returns RF/RF_max as normalized).
"triplets": mean fraction of triplets correctly resolved.
Inputs: tree_key1 (required), tree_key2 (required), dataset_id (required), metric. Returns: Result of comparing two trees.
compute_dissimilarityA
Compute a pairwise dissimilarity map over cells (useful before nj/upgma).
Stores the result in tdata.obsp[key_added]. Returns a short confirmation.
Args: dataset_id: Dataset handle. method: Dissimilarity metric (e.g. nonmissing_hamming, weighted_hamming, hamming). characters_key: obsm key holding the character matrix. key_added: obsp key to store the distance map under.
Inputs: dataset_id (required), method, key_added, characters_key. Returns: result
compute_heritabilityA
Rank features by heritability on a tree (Moran's I / Geary's C autocorrelation).
Answers "which genes are most heritable on this lineage tree?". Builds tree neighbors, then computes spatial autocorrelation of each feature over that graph. Requires an expression/feature matrix in .X (or a named layer): var_names are the features scored. Results are also stored in tdata.uns["moranI"]/["gearyC"].
Args: dataset_id: Dataset handle. tree_key: Which tree in obst to use. keys: Feature names to score (default: all var_names). n_neighbors: Number of tree neighbors per cell for the connectivity graph. method: "moran" (Moran's I) or "geary" (Geary's C). layer: Optional layer to use instead of .X. top_n: Number of top-ranked features to return.
Inputs: tree_key (required), dataset_id (required), keys, layer, +3 more. Returns: Ranked heritability table over features on a tree.
dataset_infoB
Inspect a loaded dataset: shape, tree keys, obsm/obs/layers/uns keys.
Inputs: dataset_id (required). Returns: Summary of a stored TreeData object.
export_newickA
Export a reconstructed tree to a Newick string.
Args: dataset_id: Dataset handle. tree_key: Which tree in tdata.obst to export. record_branch_lengths: Include branch lengths in the Newick. record_node_names: Include internal node names in the Newick.
Inputs: tree_key (required), dataset_id (required), record_node_names, record_branch_lengths. Returns: A tree serialized to Newick text.
import_character_matrixA
Import a character-matrix CSV into a new TreeData, ready for reconstruction.
The CSV must have cell ids in the first column and one column per character;
integer states, with missing_state for dropout and unmodified_state for
the uncut state. The matrix is stored in obsm[characters_key].
Args: csv_path: Absolute path to the character-matrix CSV. characters_key: obsm key to store the matrix under (default "characters"). missing_state: Sentinel for missing/dropout entries (default -1). unmodified_state: Sentinel for the uncut/unmodified state (default 0).
Inputs: csv_path (required), missing_state, characters_key, unmodified_state. Returns: Summary of a stored TreeData object.
label_cladesB
Partition a tree into clades at a given depth; labels written to obs[key_added].
Inputs: tree_key (required), dataset_id (required), depth, key_added. Returns: result
launch_viewerA
Launch the cellxlineage interactive web viewer on a dataset.
Accepts a loaded dataset_id (persisted to .h5td automatically) or a path to an
existing .h5td file. Spawns cellxlineage launch as a background process and
returns the URL and PID (stop it with the PID when done).
Requires the optional cellxlineage package to be installed (see the error
message if it is missing). Note: this starts a long-running web server on the
host running the MCP server.
Args: dataset_id_or_path: A loaded dataset_id or a path to a .h5td file. port: Port to serve on. host: Host/interface to bind.
Inputs: dataset_id_or_path (required), host, port. Returns: Handle for a launched cellxlineage viewer process.
list_datasetsA
List all datasets currently loaded in the session.
Inputs: no named parameters. Returns: result
load_datasetA
Load a TreeData file (.h5td, or legacy .h5ad) into the session.
Use this for existing datasets that already contain trees, expression, and/or a character matrix. Returns a dataset_id handle plus a summary of contents.
Args: path: Absolute path to a .h5td/.h5ad file.
Inputs: path (required). Returns: Summary of a stored TreeData object.
load_example_datasetA
Load a built-in pycea example lineage-tracing dataset (downloaded on first use).
Great for demos and testing without your own data. Each returns a TreeData with a tree and (for most) expression, ready for plotting and heritability.
Datasets:
"packer19": C. elegans embryo lineage (option {"tree": "full"|"observed"}).
"yang22": mouse tumor phylogenies (option {"tumors": "3435_NT_T1"}).
"koblan25": prime-editing lineage tracing (option {"experiment": "tumor"}).
Args: name: One of packer19, yang22, koblan25. options: Keyword args forwarded to the pycea.datasets loader.
Inputs: name, options. Returns: Summary of a stored TreeData object.
plot_treeA
Plot a lineage tree, optionally with a character-matrix / annotation heatmap.
Renders with pycea and returns the figure inline plus the path it was saved to.
Use keys to draw annotation bars beside the leaves -- pass the character-matrix
obsm key (e.g. "characters"), obs columns, or gene names to visualize alongside
the tree.
Args: dataset_id: Dataset handle. tree_key: Which tree in obst to plot. keys: Annotation(s) to draw beside the tree (obsm key, obs cols, or var_names). polar: Draw the tree radially instead of rectangularly. branch_color: Edge color, or an edge/obs attribute name to color by. node_color: Optional node color or attribute name. annotation_width: Width of each annotation column (fraction of plot). depth_key: Node attribute to use for depth/branch lengths (default: topological). width: Figure width in inches. height: Figure height in inches. dpi: Figure resolution. save_path: Where to write the PNG (default: /plots/_.png).
Inputs: tree_key (required), dataset_id (required), dpi, keys, +8 more.
reconstruct_ancestral_statesA
Infer internal-node states for the given keys (obs cols / var / obsm) on a tree.
Methods include "mean" (continuous) and parsimony-based (Fitch-Hartigan / Sankoff) depending on the data. Results are written as node attributes on the tree.
Inputs: keys (required), tree_key (required), dataset_id (required), method. Returns: result
reconstruct_treeA
Reconstruct a lineage tree from a dataset's character matrix.
The tree is written into tdata.obst[key_added] as a rooted networkx DiGraph.
Methods:
"greedy": Cassiopeia-Greedy (fast, top-down; good default).
"nj": Neighbor-Joining (distance-based).
"upgma": UPGMA (distance-based, ultrametric).
"ilp": Steiner-tree ILP (exact; requires Gurobi; small trees only).
"hybrid": greedy top + ILP bottom (requires Gurobi).
Args: dataset_id: Dataset handle (must contain a character matrix in obsm). method: One of greedy, nj, upgma, ilp, hybrid. key_added: obst key for the new tree (defaults to the method name). characters_key: obsm key holding the character matrix. priors: Whether to use mutation priors from uns["priors"] if present. extra_options: Advanced solver kwargs passed through (e.g. {"root": "midpoint"} for nj, {"top_solver": "greedy"} for hybrid).
Inputs: dataset_id (required), method, priors, key_added, +2 more. Returns: Result of a tree-reconstruction solver run.
save_datasetC
Persist a dataset to a .h5td file (default: /<dataset_id>.h5td).
Returns the absolute path written.
Inputs: dataset_id (required), path. Returns: result
simulate_charactersA
Simulate a lineage-tracing character matrix on a dataset's simulated tree.
Populates obsm["characters"] via stochastic Cas9-style tracing, optionally adding heritable/stochastic missing data and sequencing noise.
Args: dataset_id: Dataset handle containing a simulated tree. mutation_rate: Per-site mutation (cut) rate. number_of_cassettes: Number of independent cassettes. size_of_cassette: Number of characters per cassette. number_of_states: Number of possible indel states per character. add_missing: Apply cassiopeia.sim.missing_data after tracing. add_noise: Apply cassiopeia.sim.noise (miscalls) after tracing. extra_options: Extra kwargs forwarded to stochastic_tracing.
Inputs: dataset_id (required), add_noise, add_missing, extra_options, +4 more. Returns: Summary of a stored TreeData object.
simulate_treeA
Simulate a ground-truth tree topology and register it as a new dataset.
Methods:
"complete_binary": a complete binary tree (pass e.g. {"depth": 6} or {"num_cells": 64} in extra_options).
"birth_death": a birth-death process (pass e.g. {"birth_rate": 1.0, "death_rate": 0.0, "num_extant": 100} in extra_options).
The tree is stored in obst[key_added]. Follow with simulate_characters to add a character matrix for benchmarking reconstruction.
Args: method: "complete_binary" or "birth_death". key_added: obst key for the simulated tree. extra_options: Keyword args forwarded to the cassiopeia.sim function.
Inputs: method, key_added, extra_options. Returns: Summary of a stored TreeData object.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct operation in the lineage tracing pipeline: data import, simulation, reconstruction, analysis, and visualization. No two tools have overlapping functionality that would cause confusion.
Most tools follow a verb_noun pattern (e.g., simulate_tree, plot_tree, load_dataset). However, 'dataset_info' deviates as noun_noun, and 'label_clades' is verb_noun but could be better as 'label_clades' is fine. Overall consistency is high with minor exceptions.
18 tools cover the full workflow of lineage tracing without being excessive. Each tool has a clear purpose, and the count is appropriate for the domain's complexity.
The toolset provides a complete pipeline: import, simulate, reconstruct, analyze (parsimony, heritability, distances), visualize, and manage datasets. No obvious gaps for the intended use case.
Maintenance
Related MCP Connectors
Human Lineage MCP server — search and query the public genealogical graph of all humanity
MCP gateway federating 22 biomedical MCP servers behind one endpoint: gnomAD, ClinVar, HPO, VEP.
MCP server for Drosophila neuroscience data from VirtualFlyBrain
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
Related MCP Servers
- AlicenseCqualityDmaintenanceAn MCP server that enables single-cell RNA sequencing analysis through natural language, supporting data processing, visualization, and analysis tasks without requiring coding knowledge.5212BSD 3-Clause
- AlicenseBqualityBmaintenanceNatural language-driven spatial transcriptomics analysis via MCP. Integrates 60+ methods for preprocessing, visualization, spatial statistics, cell communication, deconvolution, and trajectory analysis.20146 PyPI46MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables scRNA-Seq analysis through natural language, providing tools for data preprocessing, clustering, and biological visualization. It supports both predefined function execution and a flexible code mode powered by a Jupyter backend for automated single-cell transcriptomics workflows.16 PyPI16BSD 3-Clause
- AlicenseAqualityDmaintenanceAn MCP server for searching and accessing RNA sequencing datasets from the European Nucleotide Archive (ENA), supporting bulk, single-cell, and spatial transcriptomics with advanced filtering and download capabilities.111,224 PyPI1Apache 2.0