mudm-mcp
Ask an AI assistant about the muDM spatial-data catalog: about 100 public datasets of spatial transcriptomics and proteomics (Xenium, CODEX, CosMx, MERSCOPE, MIBI, Visium), Drosophila EM connectomes and 3D reference anatomy.
mudm-mcp is a small Model Context Protocol server that runs on your own
machine. Your assistant (Claude Code, Claude Desktop, Cursor, …) starts it, and through it can find datasets,
describe them, query per-cell and per-neuron attributes, count cells in a region, and download data for local
analysis. There is no account, no API key and no hosted backend: it reads the public static catalog.
Quickstart
You need uv.
Claude Code
claude mcp add mudm -- uvx mudm-mcp
Start a new session and type /mcp: mudm should be listed as connected.
Claude Desktop — add this to claude_desktop_config.json (Settings → Developer → Edit Config) and restart:
{
"mcpServers": {
"mudm": { "command": "uvx", "args": ["mudm-mcp"] }
}
}
If Claude Desktop reports that it cannot find uvx, give its full path instead (run which uvx; typically
/Users/you/.local/bin/uvx).
Any other MCP host — register a stdio server with the command uvx mudm-mcp.
From a source checkout — no PyPI needed; use this to run an unreleased version. Clone this repository, then
give the host the checkout's path instead of uvx mudm-mcp:
claude mcp add mudm -- uv run --directory /path/to/mudm-mcp mudm-mcp
The first launch downloads the Python dependencies (about 0.5 GB into uv's cache, a few seconds on a fast
connection); later launches start in under a second. The first query_facets call also fetches DuckDB's
httpfs extension (about 20 MB) from DuckDB's extension server.
Then ask, for example:
- "Find a mouse brain spatial transcriptomics dataset in muDM and describe it."
- "How many cells are in the 500 µm square from (2000, 2000) to (2500, 2500) of that section?"
- "How many Kenyon cells are in the hemibrain connectome, by type?"
- "Which genes have the most transcripts in the Xenium mouse brain coronal section?"
docs/demo.md is a ten-minute walk-through of these prompts with the answers to expect.
To remove the server again: claude mcp remove mudm (or delete the entry from the Claude Desktop config).
Tools
| Tool | What it does | Downloads data? |
|---|---|---|
search_datasets |
Find datasets by free text ("mouse brain") or by modality, organism, technique, tissue |
no |
describe_dataset |
What a dataset contains: assay, license, citation, layers, columns, attributes, units, sizes per zoom | no |
query_facets |
SQL over the per-cell / per-neuron attribute table (gene counts, markers, cell types), read in place | no |
count_features |
Count cells inside a rectangle given in micrometres, optionally grouped by a tag (2D datasets) | a few MB, once |
get_access |
URLs and a decode snippet for reading the data directly, outside this server | no |
download |
Fetch one zoom level of the feature Parquet into the local cache | yes (size-gated) |
query |
SQL (DuckDB) over the downloaded features | no, but needs download first |
sample_patches |
Sample tiles as spatial patches, with per-feature geometry summaries (for ML) | no, but needs download first |
get_lod |
Summarise one level of detail of the downloaded data | no, but needs download first |
Things worth knowing
Units. Datasets store their vertices in different units: Xenium in image pixels (0.2125 µm each), the other
2D platforms in micrometres, the connectomes in nanometres, the reference anatomy in metres. describe_dataset
reports the stored unit and the factor to micrometres, and every tool argument or result named *_um is in
micrometres, already converted.
Geometry is not GeoParquet. Feature geometry is muDM binary tile geometry (packed float32 vertices), so SQL
cannot filter on coordinates. Use count_features for regions and sample_patches for geometry;
get_access returns a three-line Python snippet for decoding it yourself.
Downloads are size-gated. A download estimated above 500 MB is not started; the tool reports the size and
cheaper options, and proceeds only with confirm_large=true. (The hemibrain at full resolution is about 300 GB.)
Most questions need no download at all: query_facets reads the remote file in place.
SQL is sandboxed and bounded. query and query_facets accept one read-only SELECT. The DuckDB connection
can read only the dataset it was opened for: no other files or URLs, no writes. Results are capped (200 rows by
default) and flagged truncated when more exist.
Cache. Downloads and catalog metadata live in ~/.cache/mudm-mcp/ (override with MUDM_CACHE_DIR or
--cache-dir). Catalog metadata refreshes after 24 hours. Delete the directory to reclaim space.
Another catalog. --base-url (or MUDM_BASE_URL) points the server at a different muDM static catalog,
including a local build directory.
Development
uv sync
uv run pytest tests/ -x --tb=short # offline tests
uv run pytest -m live # contract tests against the live catalog
uv run python scripts/host_smoke.py # drive the server over stdio, end to end
Part of the muDM family
mudm— the data modelmudm-tools— the tiling/conversion engine and viewersmudm-data— produces and serves the static catalog this client reads
License
MIT. The datasets carry their own licenses and citations; describe_dataset reports them.
Metadata
Release files for mudm-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mudm_mcp-0.1.0.tar.gz | 48.6 kB | Without provenance | Details for mudm_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mudm_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mudm_mcp-0.1.0-py3-none-any.whl |
Total release size: 84.6 kB
Release files / mudm_mcp-0.1.0.tar.gz
| Download URL | mudm_mcp-0.1.0.tar.gz |
|---|---|
| Size | 48.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
57de5f1d6e4a03cf53b6c5aceec367e5ef48f677a98d0bba1c8ab7369d5bec35
|
|
BLAKE2b-256 checksum How to use checksums |
d236c6ee3292b73d9dd40f1072b5b3258bc3e7897c7a6baba6890cd0f30fd50a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mudm_mcp-0.1.0-py3-none-any.whl
| Download URL | mudm_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b799d899d186923bf4b92bfe6f21ce564d7ff802044ce0254a26088b525c4e90
|
|
BLAKE2b-256 checksum How to use checksums |
55b04f05af5b725a5de16bcba255a1b4ccdfa5c25ff0e6144bc8e6e93d9a24db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mudm-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.