Query and download public cancer imaging data from NCI Imaging Data Commons. Invoke for any question about IDC collections, cancer imaging datasets, DICOM data access, radiology (CT, MR, PET) or pathology AI training sets, metadata queries, visualization, or license checks — even when the user doesn

Imaging Data Commons Overview Query and download public cancer imaging data from the National Cancer Institute Imaging Data Commons (IDC). No authentication required for data access. Expected network access: IDC metadata is reachable three ways — a local DuckDB index shipped with the idc index Python package (no network), or the hosted IDC service over MCP or REST ( api.imaging.datacommons.cancer.gov , no authentication). File downloads use public GCS ( storage.googleapis.com ) and AWS S3 ( s3.amazonaws.com ) — no authentication required. DICOMweb access uses either the public IDC proxy ( proxy.imaging.datacommons.cancer.gov , no auth) or the Google Cloud Healthcare API ( healthcare.googleapis.com , requires GCP authentication). Optional BigQuery queries ( bigquery.googleapis.com ) also require GCP authentication. No credentials or environment variables are accessed by this skill. Current IDC Data Version: v24 (always verify — see Best Practices ) Choose the access path first. There is no single default: the cheapest correct path depends on the session and the task. 1. Session already has the IDC MCP server? Route discovery and metadata there — see IDC MCP Server . 2. Otherwise, is idc index installed? Run python scripts/check version.py . If it passes, use idc index for everything. 3. Not installed, and the task is read only metadata — counts, attribute values, collection lookups, SQL under 10 000 rows, licenses, citations, viewer URLs? Use the REST API over curl ; do not install anything. Installing costs ~77 MB of packaged index data plus pandas, pyarrow, and duckdb, which a metadata question does not need. See Data Access Options . 4. Not installed, and the task needs more than metadata — downloading files, pandas or plotting, pydicom/SimpleITK, pathology tiling, results past 10 000 rows, or a version pinned script the user re runs? Install idc index : check version.py exits non zero and prints the exact install command for the running interpreter. Prefer a virtual environment, then restart Python. idc index ([GitHub](https://github.com/imagingdatacommons/idc index)) is still the most capable path and the only one that moves image bytes; the rule is just not to pay for it before the task calls for it. check version.py never installs anything itself — it also flags a newer idc index or skill release when one exists. Setup for the idc index path: Core workflow: query metadata with client.sql query() → download with client.download from selection() → visualize with client.get viewer URL() . Python examples below assume this client ; Data Access Options has the REST equivalents. For current data scale, run the summary query in references/sql patterns.md or GET /v3/stats . IDC MCP Server IDC operates a hosted MCP server at https://api.imaging.datacommons.cancer.gov/mcp (streamable HTTP, no authentication). Where it is available it complements — it does not replace — the idc index workflow below. Identify it by the MCP resource idc://guide , or by three or more of the tool names build cohort , get cohort urls , list analysis results , and get idc version . Generic names such as run sql are not evidence on their own. If identification is ambiguous, use idc index . If this session has the server , treat it as authoritative for discovery and metadata — IDC version, counts, attribute values, cohort building, metadata SQL — and follow the server's own instructions rather than re deriving them from this file. Its data version is whatever the server reports: call get idc version instead of relying on the version pinned in this file. Return here for what the server does not do: downloading files, local pandas/notebook analysis, DICOMweb, BigQuery, digital pathology tiling, and reproducible scripts. Hand off by passing SeriesInstanceUIDs from the server to client.download from selection(...) , and run scripts/check version.py at that point. If it is not available , the identical service is reachable with no configuration as a REST API at https://api.imaging.datacommons.cancer.gov/v3 — use it for read only metadata rather than installing idc index , per the routing gate in Overview . Suggest connecting the MCP server at most once, only for repeated interactive discovery, and never change the user's configuration yourself. See references/mcp guide.md for the tool inventory, handoff patterns, and per host notes. When to Use This Skill Finding publicly available radiology (CT, MR, PET) or pathology (slide microscopy) images Selecting image subsets by cancer type, modality, anatomical site, or other metadata Downloading DICOM data from IDC Checking data licenses before use in research or commercial applications Visualizing medical images in a browser without local DICOM viewer software Quick Navigation Inline below: the MCP/REST routing rules, the IDC data model, the index tables and how they join, the core API patterns (query, download, visualize, license, cite), best practices, and troubleshooting. Reference Guides (load on demand): Guide When to Load index tables guide.md Complex JOINs, schema discovery, DataFrame access use cases.md End to end workflows: training datasets, batch downloads, DICOM reading with pydicom/SimpleITK, pipeline integration sql patterns.md Quick SQL patterns for filter discovery, annotations, size estimation clinical data guide.md Clinical/tabular data, imaging+clinical joins, value mapping licensing and citation.md Commercial use questions, mixed license cohorts, citation formats cloud storage guide.md Direct S3/GCS access, versioning, UUID mapping dicomweb guide.md DICOMweb endpoints, PACS integration digital pathology guide.md Slide microscopy (SM), annotations (ANN), pathology workflows bigquery guide.md Full DICOM metadata, private elements (requires GCP) cli guide.md Command line tools ( idc download , manifest files) parquet access guide.md Direct Parquet queries via GCS (no idc index install needed) mcp guide.md Hosted IDC MCP server: tool inventory, identification, handoff to idc index rest api guide.md Hosted IDC REST API: endpoints, filter syntax, SQL over HTTP, manifests IDC Data Model IDC adds two grouping levels above the standard DICOM hierarchy (Patient → Study → Series → Instance): collection id : Groups patients by disease, modality, or research focus (e.g., tcga luad , nlst ). A patient belongs to exactly one collection. analysis result id : Identifies derived objects (segmentations, annotations, radiomics features) across one or more original collections. Use it to find AI generated or expert annotations, while collection id finds original imaging data (which may itself include deposited annotations). Key identifiers for queries: Identifier Scope Use for collection id Dataset grouping Filtering by project/study PatientID Patient Grouping images by patient StudyInstanceUID DICOM study Grouping of related series, visualization SeriesInstanceUID DICOM series Grouping of related series, visualization Index Tables The idc index package provides multiple metadata index tables, accessible via SQL or as pandas DataFrames. The REST API exposes the same tables through GET /tables and POST /sql . Important: client.indices overview is the authoritative source for current table descriptions, available columns, and their types — query it when writing SQL or exploring data structure. It also answers "which table contains column X"; see references/index tables guide.md for that search pattern and full schema discovery. Available Tables Always call client.fetch index("table name") before querying any index table — it is safe and idempotent for all tables, including those loaded automatically at startup. Family Tables Granularity Core index (primary metadata for all current data), collections index , analysis results index series / collection / analysis result Modality acquisition parameters ct index , mr index , pt index , contrast index 1 row = 1 series of that modality Derived objects seg index , rtstruct index , ann index , ann group index 1 row = 1 series (or annotation group) Microscopy sm index , sm instance index 1 row = 1 SM series / instance Geometry, clinical, history volume geometry index , clinical index , version metadata index , prior versions index see guide references/index tables guide.md has the full inventory with each table's columns and contents — load it when you need to know what a specialized table actually holds. prior versions index is for reproducibility only. It contains series permanently removed from IDC, with zero overlap with index . Use it only to reproduce work against a prior IDC version. Do NOT use it for version history or "what's new" questions — those use series init idc version / series revised idc version in the main index table, which are not equivalent to this table's min idc version / max idc version . Joining Tables SeriesInstanceUID is the universal join key for all series level specialized tables: sm index , sm instance index , seg index , ann index , ann group index , contrast index , volume geometry index , rtstruct index , ct index , mr index , pt index . Always join these to index on SeriesInstanceUID . The exceptions below use different column names. Join Column Tables Use Case collection id index, prior versions index, collections index, clinical index Link series to collection metadata or clinical data analysis result id index, analysis results index Link series to analysis result metadata (annotations, segmentations) source DOI index, analysis results index Link by publication DOI segmented SeriesInstanceUID seg index → index Link segmentation to its source image series ( seg index.segmented SeriesInstanceUID = index.SeriesInstanceUID ) referenced SeriesInstanceUID ann index → index, rtstruct index → index Link annotation or RTSTRUCT to its source image series Note: subjects , updated , and description appear in multiple tables but have different meanings (counts vs identifiers, different update contexts). Joining prior versions index to index on SeriesInstanceUID always returns zero rows — see the warning above. For detailed join examples, schema discovery patterns, key columns reference, and DataFrame access, see references/index tables guide.md . Clinical Data Access Clinical (non imaging) attributes — staging, demographics, therapy — live in per collection tables. client.fetch index("clinical index") loads the dictionary mapping columns to collections; client.get clinical table(name) returns one table as a DataFrame. See references/clinical data guide.md for the discovery workflow, coded value mapping, and joining clinical data with imaging. Data Access Options Method Auth Best For Reference idc index No Downloads, pandas analysis, unbounded queries — the most capable path This document IDC MCP server No Discovery, cohort building, metadata when the session already has it mcp guide.md IDC REST API No Metadata with no install, from any language or shell — the default when idc index is absent rest api guide.md Direct Parquet (GCS) No Version pinned queries, or results past the REST row cap parquet access guide.md Cloud storage (S3/GCS) No Direct file access, bulk transfer, custom pipelines cloud storage guide.md DICOMweb via IDC proxy No Tool and PACS integration; daily quota, so testing and moderate use dicomweb guide.md DICOMweb via Google Healthcare Ye

imaging-data-commons