Skip to content

Trial

Use trial commands to search and inspect clinical studies with oncology-focused filters.

Trial command model

  • search trial finds candidate studies.
  • get trial <NCT_ID> retrieves a specific study.
  • positional sections expand details.

Search trials (default source)

ClinicalTrials.gov is the default source.

biomcp search trial -c melanoma --status recruiting --limit 5

Add intervention and phase filters:

biomcp search trial -c melanoma -i pembrolizumab --phase 3 --limit 5

Add biomarker filters:

biomcp search trial -c melanoma --mutation "BRAF V600E" --limit 5
biomcp search trial -c melanoma --biomarker BRAF --limit 5

Geographic filtering:

biomcp search trial -c melanoma --lat 42.36 --lon -71.06 --distance 50 --limit 5

When geo filters are set, the search query summary includes lat, lon, and distance.

Prior-therapy filters:

biomcp search trial -c melanoma --prior-therapies platinum --limit 5
biomcp search trial -c melanoma --line-of-therapy 2L --limit 5

Search trials (NCI source)

Use NCI CTS when you want the shared BioMCP trial CLI to target the NCI trial catalog instead of ClinicalTrials.gov.

biomcp search trial -c melanoma --source nci --limit 5

--condition remains the NCI entry point. BioMCP first tries to ground the condition through MyDisease and, when the best match has an NCI Thesaurus cross-reference, sends diseases.nci_thesaurus_concept_id=<C-code>. When no grounded NCI ID is available, BioMCP falls back to CTS keyword=<text>. There is no separate NCI keyword flag in this ticket.

NCI status handling is source-specific. Use one normalized status at a time:

  • recruiting maps to CTS sites.recruitment_status=ACTIVE
  • not yet recruiting, enrolling by invitation, active, not recruiting, completed, suspended, terminated, and withdrawn map to the closest documented CTS lifecycle or site-status value
  • comma-separated status lists are rejected for --source nci

NCI phase handling is also source-specific:

  • 1, 2, 3, and 4 map to CTS I, II, III, and IV
  • 1/2 maps to CTS I_II
  • NA stays NA
  • early_phase1 is rejected for --source nci
biomcp search trial -c melanoma --source nci --status recruiting --phase 1/2 --limit 5

NCI geographic filtering is direct CTS filtering rather than CTGov's geo-verify mode. When --lat, --lon, and --distance are all present, BioMCP sends sites.org_coordinates_lat, sites.org_coordinates_lon, and sites.org_coordinates_dist=<N>mi.

biomcp search trial -c melanoma --source nci --lat 42.36 --lon -71.06 --distance 50 --limit 5

For higher limits and reliable authenticated access, set NCI_API_KEY.

Get a trial by NCT ID

biomcp get trial NCT02576665

The default response summarizes title, status, condition context, and source metadata.

Request trial sections

Eligibility:

biomcp get trial NCT02576665 eligibility

Locations:

biomcp get trial NCT02576665 locations

Outcomes:

biomcp get trial NCT02576665 outcomes

Arms/interventions:

biomcp get trial NCT02576665 arms

References:

biomcp get trial NCT02576665 references

All sections where supported:

biomcp get trial NCT02576665 all

Helper commands

There is no direct trial <helper> family. Use inbound pivots such as biomcp gene trials <gene>, biomcp variant trials <id>, biomcp drug trials <name>, or biomcp disease trials <name> when the anchor entity is already known.

Downloaded text and cache

Large text blocks (for example, eligibility text) are cached in the BioMCP download area. This keeps repeated lookups responsive.

JSON mode

biomcp --json get trial NCT02576665

Practical tips

  • Start broad on condition, then add intervention and biomarker filters.
  • Keep limits low while tuning search criteria.
  • Use eligibility section only when you need raw criteria text.