Command line and agents#

The package installs two commands: sddb-cli, a thin command line over the catalog, and sddb-mcp, a Model Context Protocol server that lets an agent such as Claude query the same catalog.

pip install "spatialdata-db @ git+https://github.com/theislab/spatialdata-db-client@v0.1.3"

sddb-cli#

Every command accepts --catalog <url-or-path> to use another catalog (default: $SDDB_CATALOG_URL, then the published catalog). Errors go to stderr with exit code 1.

query#

List datasets that match facets, ranges, a gene or free text. --validation all includes datasets that did not pass validation (in the current catalog every dataset passes, so this changes nothing yet; filter on tier for quality), --json emits records instead of a table, and --gene (repeatable, requires all) uses the gene index.

$ sddb-cli query --organism human --technology Visium --tissue lung --min-obs 5000
# catalog 2026-10-28 · 6087 datasets
uid                   technology  organism  tissue  n_obs
PntNMJy70YLUP8eq0000  Visium      human     lung    6195
gA0atNHp50LE7usk0000  Visium      human     lung    5218
B1pHBGo66lQ15oil0000  Visium      human     lung    13002
KI3j6VpkjaVwuPPY0000  Visium      human     lung    5388

Each match has a page on the DB site, e.g., PntNMJy70YLUP8eq0000.

Other options: --assay, --disease, --tier, --source (the study_id prefix, such as geo, hest or 10x), --preservation-method, --hne-image/--no-hne-image, --redistributable/--no-redistributable, --search, --min-features, --min-fraction. --search keeps datasets where every word matches a value in some facet; a word that matches nothing is ignored with a warning. Case, spaces and hyphens in a value are ignored, and --technology also accepts the website label, such as "10x Xenium". A value that is not in the catalog fails with the closest known value as a hint.

download#

Copy stores by uid into a directory (resumable) and print the path of the manifest it wrote.

$ sddb-cli download h1okQyQN4GJd0I1l0000 --dest ./data
data/manifest.json

To download every member of a collection, pass its slug (the last part of the collection page URL) instead of uids:

$ sddb-cli download --collection <slug> --dest ./data
data/manifest.json

Pass uids or --collection, not both. --workers sets the number of parallel downloads. A summary line goes to stderr when the download finishes, so stdout still holds only the manifest path. The store (h1okQyQN4GJd0I1l0000) lands in ./data/h1okQyQN4GJd0I1l0000.zarr.

viewer-url#

Print the browser viewer link for one dataset. Nothing is downloaded.

$ sddb-cli viewer-url xVK6T0rajFTgOKci0000
https://vitessce.io#?edit=false&url=data:,%257B%2522version%2522...

Dataset: xVK6T0rajFTgOKci0000.

genes#

List datasets that express all the given genes (symbols or Ensembl ids). With one gene, datasets are ranked by the fraction of observations in which it is detected. The first call downloads the cross-dataset gene index (about 900 MB, downloaded once and cached), and lookups read it in batches, so a lookup needs well under 1 GB of memory and takes about 15 seconds.

$ sddb-cli genes EPCAM --limit 3
uid                   fraction_obs_detected  total_counts  validation_status  tier
EVTMdgu8thDMETSm0000  1                      3.807e+04     pass               silver
S6yC0WUFUl8bFH5y0000  0.9997                 1.929e+05     pass               bronze
7nANAXEEhj6WHiCU0000  0.9997                 2.63e+05      pass               bronze

Datasets: EVTMdgu8thDMETSm0000, S6yC0WUFUl8bFH5y0000, 7nANAXEEhj6WHiCU0000.

genes defaults to --validation all, so datasets that failed validation are included. Pass --validation pass to exclude them. To restrict by tier, use sddb-cli query --tier ... or Catalog().query(tier=...).

cite#

Write BibTeX for the studies behind the datasets that match the facets or search.

$ sddb-cli cite -o refs.bib --organism mouse --tissue brain --technology Visium
wrote 276 citations (252 fallback; entries that share a DOI merged) -> refs.bib

A study without an entry in the published citations.bib gets a fallback entry that cites its dataset page on the website, and the output line counts those entries. Entries that cite the same DOI, such as the GEO samples of one paper, are merged into one. The command exits with an error if no datasets match at all. See 4. Citations and licenses for the fallback format.

sddb-mcp#

The MCP server speaks stdio and exposes the catalog to an agent. Install the extra:

pip install "spatialdata-db[mcp] @ git+https://github.com/theislab/spatialdata-db-client@v0.1.3"

Claude Desktop#

Add the server to claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "spatialdata-db": {
      "command": "sddb-mcp"
    }
  }
}

Claude Code#

Register it once from a terminal:

claude mcp add spatialdata-db -- sddb-mcp

or commit the same JSON as .mcp.json in your project:

{
  "mcpServers": {
    "spatialdata-db": {
      "command": "sddb-mcp"
    }
  }
}

If sddb-mcp is not on the PATH of the app, use its absolute path as command.

Tools#

Tool	What it does
`query`	Filter datasets by facets (including `source`, `preservation_method`, `hne_image`, `if_image` and `redistributable`), ranges (`min_obs`, `min_features`), gene (`expressing`, `min_fraction`) and free-text `search`.
`describe`	Catalog row and element shapes for one dataset `uid`.
`genes`	Datasets expressing one or more genes (`mode` `all` or `any`), optionally filtered by organism, tissue, disease or assay. Bronze datasets are included by default.
`features`	Datasets measuring one or more features of any modality (genes, protein targets, metabolites; labels or ids; `mode` `all` or `any`), optionally filtered by `modality`, `feature_type`, organism, tissue, disease or assay. Each row lists the typed feature hits. Bronze datasets are included by default.
`facets`	List the facet columns, or the distinct values of one field.
`cite`	BibTeX for the studies of a filtered cohort.
`download`	Plan a download (per-store and total sizes) or, with `download=true`, fetch the cohort into the server download directory.

Two limits keep an agent safe:

query returns at most MAX_ROWS = 200 rows. When there are more, the last item is a {"note": "truncated: ..."} entry telling the agent to narrow the query.
download never writes where the agent asks. Files go to the directory in the SDDB_MCP_DOWNLOAD_DIR environment variable, or to a mcp-downloads folder in the user cache directory. By default it only plans, so the agent can report sizes before anything is copied.

Set the variable in the server entry:

{
  "mcpServers": {
    "spatialdata-db": {
      "command": "sddb-mcp",
      "env": { "SDDB_MCP_DOWNLOAD_DIR": "/data/sddb-downloads" }
    }
  }
}