LLM-first REST API and MCP server for the NCI Imaging Data Commons (IDC),
backed by the idc-index Parquet index
queried locally with DuckDB. All IDC data is open — no authentication required.
One backend-agnostic core library, two thin adapters over it:
- REST API (FastAPI) — language-agnostic HTTP access with auto-generated OpenAPI docs.
- MCP server — the same capabilities as Model Context Protocol tools, so LLM agents (Claude, etc.) can query IDC directly.
Both surfaces share one core, so a capability is implemented and tested once and exposed in both.
Status: in active use. Discovery, cohort/manifest building, guarded read-only SQL, schema discovery, viewer URLs, citations, and licenses — over both REST and MCP. SQL can query and join the specialized indices (seg/ann/rtstruct, ct/mr/pt, slide microscopy, contrast/geometry) and the per-collection clinical tables, all fetched at build time; local download runs in stdio MCP mode. Still to come: an optional BigQuery backend (for per-segment detail, SR radiomics, and private DICOM elements) and CDN caching (see
dev/caching_and_cdn.md).
- User Guide — concepts, the query surfaces and how they relate, the recommended workflow, and worked REST/MCP examples. Start here to learn how to use it.
dev/architecture.md— internal design (one core, two adapters).dev/api_v3_plan.md— full design rationale + SQL threat model.dev/deployment.md— Cloud Run deployment.dev/developer_guide.md— contributing / adding capabilities.SECURITY.md— threat model, hardening in place, and how to report a vulnerability.
uv venv --python 3.12
uv pip install -e ".[dev]"
uv run --directory . pytest tests -qThe first run builds a read-only DuckDB database (cached under your temp dir, pinned to the
index version; rebuilt only when idc-index-data is upgraded). By default it also fetches the
specialized indices from idc-index releases (~40 MB), so the first build downloads data —
set IDC_API_INCLUDE_INDICES=none to build from the bundled Parquet only (no build-time
downloads, just what idc-index-data already ships). No GCP account or credentials are ever
needed.
uv run idc-api # REST API → http://127.0.0.1:8000 (Swagger at /v3/docs)
uv run idc-mcp # MCP server, stdio (local) — can also download files
uv run idc-mcp --http --host 0.0.0.0 --port 8080 # MCP server, hosted/shared (manifests only)Quick taste — build a breast-MRI cohort over REST:
curl -s localhost:8000/v3/cohort/manifest \
-H 'content-type: application/json' \
-d '{"filters": {"terms": {"Modality": ["MR"], "BodyPartExamined": ["BREAST"]}}, "page_size": 3}'For the endpoint/tool reference, MCP client setup, downloads, and configuration, see the User Guide.
Run it anywhere with the slim image:
docker build -t idc-api .
docker run -p 8080:8080 idc-api # REST APIThe image bakes the read-only DuckDB file (set via IDC_API_DUCKDB_PATH) at build time, so
cold starts are instant and the container is fully stateless (no secrets, no GCP data access).
Rebuild on each IDC release to pick up the new idc-index-data.
Cloud Run: step-by-step instructions (build/push, deploy, the DuckDB-memory sizing rule,
updating IDC versions, and the optional hosted MCP service) are in
dev/deployment.md.
Built on the NCI Imaging Data Commons (IDC). When you
publish results using IDC data, include the per-dataset citations and acknowledge IDC itself
by citing the IDC paper — Fedorov et al., 10.1148/rg.230180.
The citations capability returns both; see the
User Guide.
This software is maintained in part by the NCI Imaging Data Commons project, which has been funded in whole or in part with Federal funds from the National Cancer Institute, National Institutes of Health, Department of Health and Human Services, under task order no. HHSN26110071 under contract no. HHSN261201500003I. The statements do not necessarily reflect the views or policies of the Department of Health and Human Services, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.