Skip to main content

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 model
  • mudm-tools — the tiling/conversion engine and viewers
  • mudm-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)

Source distribution for mudm-mcp 0.1.0
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)

Table of built distributions (wheels) for mudm-mcp 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page