{ "markdown": "# cxg-census-mcp\n\n\n\n[![PyPI](https://img.shields.io/pypi/v/cxg-census-mcp.svg)](https://pypi.org/project/cxg-census-mcp/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/cxg-census-mcp.svg)](https://pypi.org/project/cxg-census-mcp/)\n[![CI](https://github.com/MaxMLang/cxg-census-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MaxMLang/cxg-census-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/MaxMLang/cxg-census-mcp/blob/main/LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://github.com/MaxMLang/cxg-census-mcp/blob/main/pyproject.toml)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)\n[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io)\n[![Status: alpha](https://img.shields.io/badge/status-alpha-orange)](https://github.com/MaxMLang/cxg-census-mcp/blob/main/CHANGELOG.md)\n[![Last commit](https://img.shields.io/github/last-commit/MaxMLang/cxg-census-mcp)](https://github.com/MaxMLang/cxg-census-mcp/commits/main)\n\nAn [MCP](https://modelcontextprotocol.io) server that lets LLM agents\nquery the [CZ CELLxGENE Discover Census](https://chanzuckerberg.github.io/cellxgene-census/)\nsingle-cell atlas without lying about it — ontology-aware filters, cost\ncaps, full provenance + attribution on every response. Drop it into\nCursor / Claude Desktop / Claude Code and ask questions like *\"Visualize the cell-type composition of the human lung\"* in plain\nEnglish.\n\n

\n \"demo\"\n

\n\n> **Independent / unaffiliated.** Not affiliated\n> with, endorsed by, or sponsored by the Chan Zuckerberg Initiative (CZI),\n> EMBL-EBI, the U.S. Census Bureau, or anyone else. \"CELLxGENE\" is a CZI\n> mark; references here are descriptive (nominative) use only.\n>\n> **No warranty.** MIT-licensed source, \"as is\". Research/exploration tool —\n> **not** a clinical or diagnostic instrument. Always verify results before\n> publication. See [LICENSE](https://github.com/MaxMLang/cxg-census-mcp/blob/main/LICENSE)\n> for the full trademark and content attribution notice, and\n> [SECURITY.md](https://github.com/MaxMLang/cxg-census-mcp/blob/main/SECURITY.md)\n> for the threat model and known-issues policy.\n\n> Alpha (v0.1.2). [`CHANGELOG.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/CHANGELOG.md)\n\n## Demos\n\n**Healthy vs COVID-19 lung, side-by-side.** Two parallel queries, the\n`disease_multi_value_v7` schema-drift rewrite kicks in for the COVID\ncohort, attribution from both contributing dataset sets surfaces in the\nsame chat turn.\n\nhttps://github.com/user-attachments/assets/c836f225-5075-4643-87aa-70d311bc5fd2\n\n**Cell-type composition of human lung in one query.** Free-text \"lung\"\nresolved to `UBERON:0002048`, routed through `tissue_general`, every CURIE\nlabeled, all in a single Tier-0 call.\n\nhttps://github.com/user-attachments/assets/b0e10ca7-e46b-4e5f-ae63-11949d328c4d\n\n(Videos render on GitHub. On PyPI they appear as bare URLs — head to the\n[GitHub README](https://github.com/MaxMLang/cxg-census-mcp#demos) to watch.)\n\nMore prompts in [`docs/example-questions.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/example-questions.md).\n\n## Architecture at a glance\n\n```\n ┌──────────────────────────────────────────────┐\n MCP client │ tools/ thin MCP wrappers, no logic │\n (Claude, ─► │ │ │\n Cursor, │ ▼ │\n Code, …) │ planner/ FilterSpec → QueryPlan, │\n │ │ cost estimate, tier routing │\n │ ▼ │\n │ ontology/ OLS4 + hint overlay, │\n │ │ CL/UBERON/MONDO expansion │\n │ ▼ │\n │ execution/ Tier 0 facet counts │\n │ │ Tier 1 chunked obs scan │\n │ │ Tier 2 expression aggregate │\n │ │ Tier 9 refuse → snippet │\n │ ▼ │\n │ clients/ OLS4 (HTTPS) + Census/SOMA │\n │ │\n │ caches/ OLS, facet, plan, filter LRU │\n │ models/ Response envelope w/ │\n │ attribution + provenance │\n └──────────────────────────────────────────────┘\n │\n ▼\n ┌────────────────────────┐\n │ EBI OLS4 (ontology) │\n │ CZ CELLxGENE Census │\n │ (CC BY 4.0 data) │\n └────────────────────────┘\n```\n\nFull architecture notes: [`docs/architecture.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/architecture.md).\nTool reference: [`docs/tool-reference.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/tool-reference.md).\nExample questions: [`docs/example-questions.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/example-questions.md).\n\n## Install\n\nFrom PyPI (recommended):\n\n```bash\nuv tool install \"cxg-census-mcp[census]\"\ncxg-census-mcp # speaks MCP over stdio\n```\n\nOr with pip:\n\n```bash\npip install \"cxg-census-mcp[census]\"\n```\n\nWithout the `[census]` extra you get **mock mode** (deterministic fixtures) —\nhandy for offline demos and verifying your MCP client config without pulling\ntiledbsoma's ~1 GB of native deps.\n\nFrom source (for development):\n\n```bash\ngit clone https://github.com/MaxMLang/cxg-census-mcp\ncd cxg-census-mcp\nuv sync --extra dev --extra census\nuv run cxg-census-mcp\n```\n\n## MCP client config\n\nCursor (`~/.cursor/mcp.json`) and Claude Desktop\n(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS)\nboth expect the same shape. Cleanest is `uvx` once installed from PyPI:\n\n```json\n{\n \"mcpServers\": {\n \"cxg-census\": {\n \"command\": \"/absolute/path/to/uvx\",\n \"args\": [\"--from\", \"cxg-census-mcp[census]\", \"cxg-census-mcp\"]\n }\n }\n}\n```\n\n> Use the **absolute** path to `uvx` (`which uvx` from your shell). MCP\n> clients spawn the server in a non-interactive subprocess that doesn't\n> source your shell rc, so a bare `\"uvx\"` will fail with\n> `No such file or directory`.\n\nIf you cloned from source instead, point at the checkout:\n\n```json\n{\n \"mcpServers\": {\n \"cxg-census\": {\n \"command\": \"/absolute/path/to/uv\",\n \"args\": [\"--directory\", \"/path/to/cxg-census-mcp\", \"run\", \"cxg-census-mcp\"]\n }\n }\n}\n```\n\nClaude Code:\n\n```bash\nclaude mcp add cxg-census -- /absolute/path/to/uvx --from \"cxg-census-mcp[census]\" cxg-census-mcp\n```\n\nQuit + relaunch your client (⌘Q on macOS — closing the window isn't enough)\nand the server should show up in the MCP panel with 13 tools.\n\n## Tools (13 total)\n\n**Workflow:** `census_summary`, `get_census_versions`, `count_cells`,\n`list_datasets`, `gene_coverage`, `aggregate_expression`, `preview_obs`,\n`export_snippet`, `get_server_limits`.\n\n**Inspection:** `resolve_term`, `expand_term`, `term_definition`,\n`list_available_values`.\n\nPlus MCP `resources` (markdown docs at `cxg-census-mcp://docs/{slug}`),\n`prompts` (`census_workflow`, `disambiguation`), and cooperative\n`progress` / `cancellation` notifications. Details in\n[`docs/tool-reference.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/tool-reference.md).\n\n## Configuration\n\nAll env vars use the `CXG_CENSUS_MCP_` prefix. Most useful:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `CXG_CENSUS_MCP_CENSUS_VERSION` | `stable` | Census release to pin |\n| `CXG_CENSUS_MCP_CACHE_DIR` | platformdirs default | Disk cache root |\n| `CXG_CENSUS_MCP_MOCK_MODE` | `0` | If `1`, never opens a real Census handle |\n| `CXG_CENSUS_MCP_LOG_LEVEL` | `WARNING` | stdlib log level |\n\nFull list and validation: `src/cxg_census_mcp/config.py`.\n\n## Development & operations\n\nQuick loop:\n\n```bash\nmake install-all # uv sync --extra dev --extra census\nmake lint typecheck test # ruff + mypy + pytest (mock mode)\nmake cov # tests + coverage HTML in ./htmlcov\nmake audit # pip-audit on locked production deps\n```\n\nOperational tasks (cache pre-warm, schema diff, container build, metrics\ndump, plan-cache vacuum, weekly hint/facet refresh) live in the\n[`Makefile`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/Makefile)\nand are documented in\n[`docs/operational-playbook.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/operational-playbook.md).\n\n## Documentation index\n\n| Topic | Where |\n|---|---|\n| System architecture | [`docs/architecture.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/architecture.md) |\n| Tool reference | [`docs/tool-reference.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/tool-reference.md) |\n| Example agent questions | [`docs/example-questions.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/example-questions.md) |\n| Ontology resolution | [`docs/ontology-resolution.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/ontology-resolution.md) |\n| Schema-drift handling | [`docs/schema-drift-format.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/schema-drift-format.md) |\n| Census version pinning | [`docs/version-pinning.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/version-pinning.md) |\n| Progress / cancellation | [`docs/progress-and-cancellation.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/progress-and-cancellation.md) |\n| Error model | [`docs/error-model.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/error-model.md) |\n| Known limitations | [`docs/limitations.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/limitations.md) |\n| Ops runbook | [`docs/operational-playbook.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/docs/operational-playbook.md) |\n| Changelog | [`CHANGELOG.md`](https://github.com/MaxMLang/cxg-census-mcp/blob/main/CHANGELOG.md) |\n\n## License & attribution\n\nSource code: [MIT](https://github.com/MaxMLang/cxg-census-mcp/blob/main/LICENSE).\nThe MIT license covers **only** the code in this repository, not the upstream\ndata, ontologies, or third-party trademarks.\n\n- **Data.** Tool responses are derived (filtered/aggregated) from the\n CZ CELLxGENE Discover Census, distributed by the Chan Zuckerberg\n Initiative under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).\n Every response carries an `attribution` field; downstream users must\n preserve attribution and indicate that changes were made.\n- **Ontologies** are fetched via EBI Ontology Lookup Service (OLS4) from\n CL, UBERON, MONDO, EFO, HANCESTRO, and others; each carries its own\n license.\n- **Trademarks** (\"CELLxGENE\", \"Cursor\", \"Claude\", \"Anthropic\", \"Model\n Context Protocol\", …) belong to their respective owners. Use here is\n descriptive only and does not imply affiliation.\n\nThis project is a *client* of the CZ CELLxGENE Discover Census; it does\nnot host, mirror, or redistribute Census data.\n\nFull notice in [LICENSE](https://github.com/MaxMLang/cxg-census-mcp/blob/main/LICENSE).\n", "bytes": 11968, "sha": "f4dfbadc6d66b39f272abdbfa42651055e1c7b96495809a845cc0c5a99333ccc", "repo_slug": "maxmlang/cxg-census-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_maxmlang_cxg_census_mcp_e36558d9/readme" }