cxg-census-mcp

cxg-census-mcp

An MCP server that lets LLM agents query the CZ CELLxGENE Discover Census single-cell atlas without lying about it — ontology-aware filters, cost caps, full provenance + attribution on every response. Drop it into Cursor / Claude Desktop / Claude Code and ask questions like *"Visualize the cell-type composition of the human lung"* in plain English.

Independent / unaffiliated. Not affiliated

with, endorsed by, or sponsored by the Chan Zuckerberg Initiative (CZI),

EMBL-EBI, the U.S. Census Bureau, or anyone else. "CELLxGENE" is a CZI

mark; references here are descriptive (nominative) use only.

No warranty. MIT-licensed source, "as is". Research/exploration tool —

not a clinical or diagnostic instrument. Always verify results before

publication. See LICENSE

for the full trademark and content attribution notice, and

SECURITY.md

for the threat model and known-issues policy.

Alpha (v0.1.2). CHANGELOG.md

Demos

Healthy vs COVID-19 lung, side-by-side. Two parallel queries, the disease_multi_value_v7 schema-drift rewrite kicks in for the COVID cohort, attribution from both contributing dataset sets surfaces in the same chat turn.

https://github.com/user-attachments/assets/c836f225-5075-4643-87aa-70d311bc5fd2

Cell-type composition of human lung in one query. Free-text "lung" resolved to UBERON:0002048, routed through tissue_general, every CURIE labeled, all in a single Tier-0 call.

https://github.com/user-attachments/assets/b0e10ca7-e46b-4e5f-ae63-11949d328c4d

(Videos render on GitHub. On PyPI they appear as bare URLs — head to the GitHub README to watch.)

More prompts in docs/example-questions.md.

Architecture at a glance

                 ┌──────────────────────────────────────────────┐

MCP client │ tools/ thin MCP wrappers, no logic │ (Claude, ─► │ │ │ Cursor, │ ▼ │ Code, …) │ planner/ FilterSpec → QueryPlan, │ │ │ cost estimate, tier routing │ │ ▼ │ │ ontology/ OLS4 + hint overlay, │ │ │ CL/UBERON/MONDO expansion │ │ ▼ │ │ execution/ Tier 0 facet counts │ │ │ Tier 1 chunked obs scan │ │ │ Tier 2 expression aggregate │ │ │ Tier 9 refuse → snippet │ │ ▼ │ │ clients/ OLS4 (HTTPS) + Census/SOMA │ │ │ │ caches/ OLS, facet, plan, filter LRU │ │ models/ Response envelope w/ │ │ attribution + provenance │ └──────────────────────────────────────────────┘ │ ▼ ┌────────────────────────┐ │ EBI OLS4 (ontology) │ │ CZ CELLxGENE Census │ │ (CC BY 4.0 data) │ └────────────────────────┘

Full architecture notes: docs/architecture.md. Tool reference: docs/tool-reference.md. Example questions: docs/example-questions.md.

Install

From PyPI (recommended):

uv tool install "cxg-census-mcp[census]"

cxg-census-mcp # speaks MCP over stdio

Or with pip:

pip install "cxg-census-mcp[census]"

Without the [census] extra you get mock mode (deterministic fixtures) — handy for offline demos and verifying your MCP client config without pulling tiledbsoma's ~1 GB of native deps.

From source (for development):

git clone https://github.com/MaxMLang/cxg-census-mcp

cd cxg-census-mcp uv sync --extra dev --extra census uv run cxg-census-mcp

MCP client config

Cursor (~/.cursor/mcp.json) and Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) both expect the same shape. Cleanest is uvx once installed from PyPI:

{

"mcpServers": { "cxg-census": { "command": "/absolute/path/to/uvx", "args": ["--from", "cxg-census-mcp[census]", "cxg-census-mcp"] } } }

Use the absolute path to uvx (which uvx from your shell). MCP

clients spawn the server in a non-interactive subprocess that doesn't

source your shell rc, so a bare "uvx" will fail with

No such file or directory.

If you cloned from source instead, point at the checkout:

{

"mcpServers": { "cxg-census": { "command": "/absolute/path/to/uv", "args": ["--directory", "/path/to/cxg-census-mcp", "run", "cxg-census-mcp"] } } }

Claude Code:

claude mcp add cxg-census -- /absolute/path/to/uvx --from "cxg-census-mcp[census]" cxg-census-mcp

Quit + relaunch your client (⌘Q on macOS — closing the window isn't enough) and the server should show up in the MCP panel with 13 tools.

Tools (13 total)

Workflow: census_summary, get_census_versions, count_cells, list_datasets, gene_coverage, aggregate_expression, preview_obs, export_snippet, get_server_limits.

Inspection: resolve_term, expand_term, term_definition, list_available_values.

Plus MCP resources (markdown docs at cxg-census-mcp://docs/{slug}), prompts (census_workflow, disambiguation), and cooperative progress / cancellation notifications. Details in docs/tool-reference.md.

Configuration

All env vars use the CXG_CENSUS_MCP_ prefix. Most useful:

Full list and validation: src/cxg_census_mcp/config.py.

Development & operations

Quick loop:

make install-all                 # uv sync --extra dev --extra census

make lint typecheck test # ruff + mypy + pytest (mock mode) make cov # tests + coverage HTML in ./htmlcov make audit # pip-audit on locked production deps

Operational tasks (cache pre-warm, schema diff, container build, metrics dump, plan-cache vacuum, weekly hint/facet refresh) live in the Makefile and are documented in docs/operational-playbook.md.

Documentation index

License & attribution

Source code: MIT. The MIT license covers only the code in this repository, not the upstream data, ontologies, or third-party trademarks.

• Data. Tool responses are derived (filtered/aggregated) from the CZ CELLxGENE Discover Census, distributed by the Chan Zuckerberg Initiative under CC BY 4.0. Every response carries an attribution field; downstream users must preserve attribution and indicate that changes were made.
• Ontologies are fetched via EBI Ontology Lookup Service (OLS4) from CL, UBERON, MONDO, EFO, HANCESTRO, and others; each carries its own license.
• Trademarks ("CELLxGENE", "Cursor", "Claude", "Anthropic", "Model Context Protocol", …) belong to their respective owners. Use here is descriptive only and does not imply affiliation.

This project is a *client* of the CZ CELLxGENE Discover Census; it does not host, mirror, or redistribute Census data.

Full notice in LICENSE.