io.github.cyanheads/clinicaltrialsgov-mcp-server

Official7 toolsLive

by cyanheads · TypeScript

Search ClinicalTrials.gov — find studies, retrieve results, match patients to eligible trials.

io.github.cyanheads/clinicaltrialsgov-mcp-server (MCP)

The io.github.cyanheads/clinicaltrialsgov-mcp-server is a Model Context Protocol (MCP) server that searches ClinicalTrials.gov. It finds studies, retrieves study details and results, and supports matching patients to eligible trials. It exposes functionality via STDIO or Streamable HTTP, and includes 7 tools.

🛠️ Key Features

Search ClinicalTrials.gov trials
Retrieve study details
Retrieve study results
Match patients to eligible trials
MCP interface via STDIO or Streamable HTTP
7 tools included

🚀 Use Cases

Locate ClinicalTrials.gov studies for investigation
Pull trial details and results for research summaries
Support patient-to-trial eligibility matching based on trial criteria

⚡ Developer Benefits

MCP server for integrating ClinicalTrials.gov into agents/workflows
Typed, tool-based access (7 tools) for trial discovery and retrieval
Transport options: STDIO and Streamable HTTP

⚠️ Limitations

No additional limitations are specified in the provided source data.

Topics

mcpmcp-serverai-agentclinical-trialseligibility-criteriahealth-techmodel-context-protocolpatient-matchingtypescriptclinicaltrials-govtrial-finderbioinformaticsresearch-toolscyanheads

Captured live from the server via tools/list.

clinicaltrials_search_studies

Search for clinical trial studies from ClinicalTrials.gov. Supports full-text and field-specific queries, status/phase/geographic filters, pagination, sorting, and field selection. Returns a compact per-study index by default; pass the fields parameter to get specific leaves at full fidelity — full study records are ~70KB each.

Parameters18

query	string	optional	General free-text search across all fields. Runs the 57-field relevance search ClinicalTrials.gov publishes for this parameter — NCTId, NCTIdAlias, OrgStudyId, SecondaryId, Acronym, BriefTitle, OfficialTitle, Condition, InterventionName, InterventionOtherName, Phase, StdAge, StudyType, BriefSummary, outcome measures and their descriptions, LeadSponsorName, CollaboratorName, the Location* fields, the Design* fields, and the ConditionAncestorTerm/InterventionAncestorTerm MeSH umbrellas — so a hit need not carry your term in the field you had in mind. Plain words plus AND, OR, NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression — those work here as well as in advancedFilter, so AREA[Phase]PHASE2 is accepted in this parameter; a stray bracket fails. `( )` group sub-expressions and work when matched; `,` acts as AND. The dedicated *Query parameters (conditionQuery, interventionQuery, etc.) scope a search to one field.
conditionQuery	string	optional	Condition/disease-specific search. E.g., "Type 2 Diabetes", "non-small cell lung cancer". Matches Condition, BriefTitle, OfficialTitle, ConditionMeshTerm, ConditionAncestorTerm, Keyword, and NCTId. ConditionAncestorTerm is the MeSH umbrella above the conditions a study itself lists, so results run broader than those lists — a study can match a parent term it never names. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
interventionQuery	string	optional	Intervention/treatment search. E.g., "pembrolizumab", "cognitive behavioral therapy". Matches InterventionName, InterventionType, ArmGroupType, InterventionOtherName, BriefTitle, OfficialTitle, ArmGroupLabel, InterventionMeshTerm, Keyword, InterventionAncestorTerm, InterventionDescription, and ArmGroupDescription. InterventionAncestorTerm is the MeSH umbrella above the interventions a study itself lists, so results run broader than those lists. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
locationQuery	string	optional	Location search — city, state, country, or facility name. Matches LocationCity, LocationState, LocationCountry, LocationFacility, and LocationZip; a study matches when any of its sites does. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
sponsorQuery	string	optional	Sponsor/collaborator name search. Matches LeadSponsorName, CollaboratorName, and OrgFullName. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
titleQuery	string	optional	Search within study titles and acronyms only. Matches Acronym, BriefTitle, and OfficialTitle. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
outcomeQuery	string	optional	Search within outcome measure fields. Matches PrimaryOutcomeMeasure, SecondaryOutcomeMeasure, OtherOutcomeMeasure, and OutcomeMeasureTitle, plus their description counterparts PrimaryOutcomeDescription, SecondaryOutcomeDescription, OtherOutcomeDescription, OutcomeMeasureDescription, and OutcomeMeasurePopulationDescription — so a term appearing only in outcome prose still matches. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
statusFilter	any	optional	Filter by study status. Omit to search all statuses — an empty list is rejected, not treated as "no filter". Values: RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION, SUSPENDED, TERMINATED, WITHDRAWN, UNKNOWN, WITHHELD, NO_LONGER_AVAILABLE, AVAILABLE, APPROVED_FOR_MARKETING, TEMPORARILY_NOT_AVAILABLE.
phaseFilter	any	optional	Filter by trial phase. Omit to search all phases — an empty list is rejected, not treated as "no filter". Values: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA.
advancedFilter	string	optional	Advanced filter using AREA[FieldName]value syntax. Examples: "AREA[StudyType]INTERVENTIONAL", "AREA[EnrollmentCount]RANGE[100, 1000]", "AREA[Phase]PHASE2 AND AREA[StudyType]INTERVENTIONAL", "(AREA[Phase]PHASE3 OR AREA[Phase]PHASE4) AND AREA[StudyType]INTERVENTIONAL". AND/OR/NOT join complete AREA[FieldName]value expressions; parentheses group them. Call clinicaltrials_get_field_definitions to find AREA[]-compatible field names.
geoFilter	string	optional	Geographic proximity filter. Format: distance(lat,lon,radius), where radius carries a `mi` or `km` suffix — e.g. "distance(47.6062,-122.3321,50mi)" for studies within 50 miles of Seattle. The suffix is required: a radius with no unit is rejected, as are a non-positive radius, a latitude outside [-90, 90], and a longitude outside [-180, 180]. When set, each study's locations are re-sorted by proximity to the center so the nearest matched site leads, annotated with its distance in miles; the full location list is preserved.
nctIds	any	optional	Filter to specific NCT IDs for batch lookups. Omit to search every study — an empty list is rejected, not treated as "no filter". Supplying this lifts the default unknown-enrollment exclusion, so an ID you name is never filtered out of its own lookup.
fields	array	optional	PascalCase leaf names to return; strongly recommended since full records are ~70KB. Omit for the compact index projection — an empty list is rejected, not treated as omission. Common leaves: NCTId, BriefTitle, BriefSummary, OverallStatus, Phase, LeadSponsorName, Condition. Call clinicaltrials_get_field_definitions with a concept query (e.g., "adverse events", "eligibility") to find the exact leaf for any concept.
sort	string	optional	Sort order. Format: FieldName:asc or FieldName:desc. E.g., "LastUpdatePostDate:desc", "EnrollmentCount:desc". Max 2 fields comma-separated. For "largest trials" queries, pair EnrollmentCount:desc with advancedFilter "AREA[StudyType]INTERVENTIONAL" — the top enrollment counts are observational registry/claims studies enrolling tens of millions. Enrollment counts are sponsor-reported and not validated upstream beyond the unknown-enrollment sentinel exclusion. Use clinicaltrials_get_field_definitions to find sortable field names.
pageSize	integer	optional	Results per page, 1–200.
pageToken	string	optional	Pagination cursor from a previous response.
countTotal	boolean	optional	Include total study count in response. Only computed on the first page.
includeUnknownEnrollment	boolean	optional	Include studies whose EnrollmentCount is the upstream "unknown" sentinel (99999999). Excluded by default — the sentinel pollutes RANGE[N, MAX] queries and EnrollmentCount:desc sorts. Set true for data-quality audits or when targeting unknown-enrollment studies specifically.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "General free-text search across all fields. Runs the 57-field relevance search ClinicalTrials.gov publishes for this parameter — NCTId, NCTIdAlias, OrgStudyId, SecondaryId, Acronym, BriefTitle, OfficialTitle, Condition, InterventionName, InterventionOtherName, Phase, StdAge, StudyType, BriefSummary, outcome measures and their descriptions, LeadSponsorName, CollaboratorName, the Location* fields, the Design* fields, and the ConditionAncestorTerm/InterventionAncestorTerm MeSH umbrellas — so a hit need not carry your term in the field you had in mind. Plain words plus AND, OR, NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression — those work here as well as in advancedFilter, so AREA[Phase]PHASE2 is accepted in this parameter; a stray bracket fails. `( )` group sub-expressions and work when matched; `,` acts as AND. The dedicated *Query parameters (conditionQuery, interventionQuery, etc.) scope a search to one field.",
      "type": "string"
    },
    "conditionQuery": {
      "description": "Condition/disease-specific search. E.g., \"Type 2 Diabetes\", \"non-small cell lung cancer\". Matches Condition, BriefTitle, OfficialTitle, ConditionMeshTerm, ConditionAncestorTerm, Keyword, and NCTId. ConditionAncestorTerm is the MeSH umbrella above the conditions a study itself lists, so results run broader than those lists — a study can match a parent term it never names. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "interventionQuery": {
      "description": "Intervention/treatment search. E.g., \"pembrolizumab\", \"cognitive behavioral therapy\". Matches InterventionName, InterventionType, ArmGroupType, InterventionOtherName, BriefTitle, OfficialTitle, ArmGroupLabel, InterventionMeshTerm, Keyword, InterventionAncestorTerm, InterventionDescription, and ArmGroupDescription. InterventionAncestorTerm is the MeSH umbrella above the interventions a study itself lists, so results run broader than those lists. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "locationQuery": {
      "description": "Location search — city, state, country, or facility name. Matches LocationCity, LocationState, LocationCountry, LocationFacility, and LocationZip; a study matches when any of its sites does. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "sponsorQuery": {
      "description": "Sponsor/collaborator name search. Matches LeadSponsorName, CollaboratorName, and OrgFullName. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "titleQuery": {
      "description": "Search within study titles and acronyms only. Matches Acronym, BriefTitle, and OfficialTitle. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "outcomeQuery": {
      "description": "Search within outcome measure fields. Matches PrimaryOutcomeMeasure, SecondaryOutcomeMeasure, OtherOutcomeMeasure, and OutcomeMeasureTitle, plus their description counterparts PrimaryOutcomeDescription, SecondaryOutcomeDescription, OtherOutcomeDescription, OutcomeMeasureDescription, and OutcomeMeasurePopulationDescription — so a term appearing only in outcome prose still matches. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "statusFilter": {
      "description": "Filter by study status. Omit to search all statuses — an empty list is rejected, not treated as \"no filter\". Values: RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION, SUSPENDED, TERMINATED, WITHDRAWN, UNKNOWN, WITHHELD, NO_LONGER_AVAILABLE, AVAILABLE, APPROVED_FOR_MARKETING, TEMPORARILY_NOT_AVAILABLE.",
      "anyOf": [
        {
          "type": "string",
          "description": "A single status value."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Multiple status values (OR)."
        }
      ]
    },
    "phaseFilter": {
      "description": "Filter by trial phase. Omit to search all phases — an empty list is rejected, not treated as \"no filter\". Values: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA.",
      "anyOf": [
        {
          "type": "string",
          "description": "A single phase value."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Multiple phase values (OR)."
        }
      ]
    },
    "advancedFilter": {
      "description": "Advanced filter using AREA[FieldName]value syntax. Examples: \"AREA[StudyType]INTERVENTIONAL\", \"AREA[EnrollmentCount]RANGE[100, 1000]\", \"AREA[Phase]PHASE2 AND AREA[StudyType]INTERVENTIONAL\", \"(AREA[Phase]PHASE3 OR AREA[Phase]PHASE4) AND AREA[StudyType]INTERVENTIONAL\". AND/OR/NOT join complete AREA[FieldName]value expressions; parentheses group them. Call clinicaltrials_get_field_definitions to find AREA[]-compatible field names.",
      "type": "string"
    },
    "geoFilter": {
      "description": "Geographic proximity filter. Format: distance(lat,lon,radius), where radius carries a `mi` or `km` suffix — e.g. \"distance(47.6062,-122.3321,50mi)\" for studies within 50 miles of Seattle. The suffix is required: a radius with no unit is rejected, as are a non-positive radius, a latitude outside [-90, 90], and a longitude outside [-180, 180]. When set, each study's locations are re-sorted by proximity to the center so the nearest matched site leads, annotated with its distance in miles; the full location list is preserved.",
      "type": "string"
    },
    "nctIds": {
      "description": "Filter to specific NCT IDs for batch lookups. Omit to search every study — an empty list is rejected, not treated as \"no filter\". Supplying this lifts the default unknown-enrollment exclusion, so an ID you name is never filtered out of its own lookup.",
      "anyOf": [
        {
          "type": "string",
          "pattern": "^NCT\\d{8}$",
          "description": "A single NCT ID."
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^NCT\\d{8}$"
          },
          "description": "Multiple NCT IDs (OR)."
        }
      ]
    },
    "fields": {
      "description": "PascalCase leaf names to return; strongly recommended since full records are ~70KB. Omit for the compact index projection — an empty list is rejected, not treated as omission. Common leaves: NCTId, BriefTitle, BriefSummary, OverallStatus, Phase, LeadSponsorName, Condition. Call clinicaltrials_get_field_definitions with a concept query (e.g., \"adverse events\", \"eligibility\") to find the exact leaf for any concept.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sort": {
      "description": "Sort order. Format: FieldName:asc or FieldName:desc. E.g., \"LastUpdatePostDate:desc\", \"EnrollmentCount:desc\". Max 2 fields comma-separated. For \"largest trials\" queries, pair EnrollmentCount:desc with advancedFilter \"AREA[StudyType]INTERVENTIONAL\" — the top enrollment counts are observational registry/claims studies enrolling tens of millions. Enrollment counts are sponsor-reported and not validated upstream beyond the unknown-enrollment sentinel exclusion. Use clinicaltrials_get_field_definitions to find sortable field names.",
      "type": "string"
    },
    "pageSize": {
      "default": 10,
      "description": "Results per page, 1–200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "pageToken": {
      "description": "Pagination cursor from a previous response.",
      "type": "string"
    },
    "countTotal": {
      "default": true,
      "description": "Include total study count in response. Only computed on the first page.",
      "type": "boolean"
    },
    "includeUnknownEnrollment": {
      "default": false,
      "description": "Include studies whose EnrollmentCount is the upstream \"unknown\" sentinel (99999999). Excluded by default — the sentinel pollutes RANGE[N, MAX] queries and EnrollmentCount:desc sorts. Set true for data-quality audits or when targeting unknown-enrollment studies specifically.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

clinicaltrials_get_study_record

Fetch a single clinical trial study by NCT ID from ClinicalTrials.gov. Returns the full study record including protocol details, eligibility criteria, outcomes, arms, interventions, contacts, and locations. Optional locationLimit / outcomeLimit / referenceLimit / nearLocation parameters trim locations, outcomes, and references — original totals are preserved in `filtersApplied` only when a cap actually trims the set.

Parameters5

nctId	string	required	NCT identifier — format `NCT` followed by 8 digits (e.g., `NCT03722472`).
locationLimit	integer	optional	Optional cap on the number of locations returned. Omit for no cap (full upstream list). Pairs naturally with nearLocation for narrowing a large multi-site trial. Original total preserved in filtersApplied.totalLocations only when the cap trims the list.
outcomeLimit	integer	optional	Optional cap on the number of secondary and other outcomes returned. Omit for no cap (full upstream lists). Primary outcomes are never capped. Original totals preserved in filtersApplied.totalSecondaryOutcomes / totalOtherOutcomes only when the cap trims a list.
referenceLimit	integer	optional	Optional cap on the number of references returned. Omit for no cap (full upstream list). Original total preserved in filtersApplied.totalReferences only when the cap trims the list. seeAlsoLinks are never capped.
nearLocation	object	optional	Filter returned locations to those within radius of (lat, lon) and sort by distance. Adds distanceMi to each location. Locations without published coordinates are dropped — most US sites carry them; international sites less reliably so. Distances reflect ClinicalTrials.gov geocoding granularity — typically city-centroid, not facility-level — so multiple sites in the same city resolve to near-identical distances. For broader geographic filtering across studies, use clinicaltrials_search_studies with geoFilter.

Raw schema

{
  "type": "object",
  "properties": {
    "nctId": {
      "type": "string",
      "pattern": "^NCT\\d{8}$",
      "description": "NCT identifier — format `NCT` followed by 8 digits (e.g., `NCT03722472`)."
    },
    "locationLimit": {
      "description": "Optional cap on the number of locations returned. Omit for no cap (full upstream list). Pairs naturally with nearLocation for narrowing a large multi-site trial. Original total preserved in filtersApplied.totalLocations only when the cap trims the list.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "outcomeLimit": {
      "description": "Optional cap on the number of secondary and other outcomes returned. Omit for no cap (full upstream lists). Primary outcomes are never capped. Original totals preserved in filtersApplied.totalSecondaryOutcomes / totalOtherOutcomes only when the cap trims a list.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "referenceLimit": {
      "description": "Optional cap on the number of references returned. Omit for no cap (full upstream list). Original total preserved in filtersApplied.totalReferences only when the cap trims the list. seeAlsoLinks are never capped.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "nearLocation": {
      "description": "Filter returned locations to those within radius of (lat, lon) and sort by distance. Adds distanceMi to each location. Locations without published coordinates are dropped — most US sites carry them; international sites less reliably so. Distances reflect ClinicalTrials.gov geocoding granularity — typically city-centroid, not facility-level — so multiple sites in the same city resolve to near-identical distances. For broader geographic filtering across studies, use clinicaltrials_search_studies with geoFilter.",
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Latitude in decimal degrees."
        },
        "lon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Longitude in decimal degrees."
        },
        "radiusMi": {
          "default": 50,
          "description": "Radius in miles. Default 50.",
          "type": "number",
          "minimum": 1,
          "maximum": 500
        }
      },
      "required": [
        "lat",
        "lon"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "nctId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

clinicaltrials_get_study_count

Get total clinical trial study count from ClinicalTrials.gov matching a query, without fetching study data. Fast and lightweight. Use for quick statistics or to build breakdowns by calling multiple times with different filters (e.g., count by phase, count by status, count recruiting vs completed for a condition).

Parameters11

query	string	optional	General free-text search across all fields. Runs the 57-field relevance search ClinicalTrials.gov publishes for this parameter — NCTId, NCTIdAlias, OrgStudyId, SecondaryId, Acronym, BriefTitle, OfficialTitle, Condition, InterventionName, InterventionOtherName, Phase, StdAge, StudyType, BriefSummary, outcome measures and their descriptions, LeadSponsorName, CollaboratorName, the Location* fields, the Design* fields, and the ConditionAncestorTerm/InterventionAncestorTerm MeSH umbrellas — so a hit need not carry your term in the field you had in mind. Plain words plus AND, OR, NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression — those work here as well as in advancedFilter, so AREA[Phase]PHASE2 is accepted in this parameter; a stray bracket fails. `( )` group sub-expressions and work when matched; `,` acts as AND. The dedicated *Query parameters (conditionQuery, interventionQuery, etc.) scope a search to one field.
conditionQuery	string	optional	Condition/disease-specific search. E.g., "Type 2 Diabetes", "non-small cell lung cancer". Matches Condition, BriefTitle, OfficialTitle, ConditionMeshTerm, ConditionAncestorTerm, Keyword, and NCTId. ConditionAncestorTerm is the MeSH umbrella above the conditions a study itself lists, so results run broader than those lists — a study can match a parent term it never names. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
interventionQuery	string	optional	Intervention/treatment search. E.g., "pembrolizumab", "cognitive behavioral therapy". Matches InterventionName, InterventionType, ArmGroupType, InterventionOtherName, BriefTitle, OfficialTitle, ArmGroupLabel, InterventionMeshTerm, Keyword, InterventionAncestorTerm, InterventionDescription, and ArmGroupDescription. InterventionAncestorTerm is the MeSH umbrella above the interventions a study itself lists, so results run broader than those lists. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
locationQuery	string	optional	Location search — city, state, country, or facility name. Matches LocationCity, LocationState, LocationCountry, LocationFacility, and LocationZip; a study matches when any of its sites does. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
sponsorQuery	string	optional	Sponsor/collaborator name search. Matches LeadSponsorName, CollaboratorName, and OrgFullName. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
titleQuery	string	optional	Search within study titles and acronyms only. Matches Acronym, BriefTitle, and OfficialTitle. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
outcomeQuery	string	optional	Search within outcome measure fields. Matches PrimaryOutcomeMeasure, SecondaryOutcomeMeasure, OtherOutcomeMeasure, and OutcomeMeasureTitle, plus their description counterparts PrimaryOutcomeDescription, SecondaryOutcomeDescription, OtherOutcomeDescription, OutcomeMeasureDescription, and OutcomeMeasurePopulationDescription — so a term appearing only in outcome prose still matches. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.
statusFilter	any	optional	Filter by study status. Omit to count all statuses — an empty list is rejected, not treated as "no filter". Values: RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION, SUSPENDED, TERMINATED, WITHDRAWN, UNKNOWN, WITHHELD, NO_LONGER_AVAILABLE, AVAILABLE, APPROVED_FOR_MARKETING, TEMPORARILY_NOT_AVAILABLE.
phaseFilter	any	optional	Filter by trial phase. Omit to count all phases — an empty list is rejected, not treated as "no filter". Values: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA.
advancedFilter	string	optional	Advanced filter using AREA[FieldName]value syntax. Examples: "AREA[StudyType]INTERVENTIONAL", "AREA[EnrollmentCount]RANGE[100, 1000]", "AREA[Phase]PHASE2 AND AREA[StudyType]INTERVENTIONAL", "(AREA[Phase]PHASE3 OR AREA[Phase]PHASE4) AND AREA[StudyType]INTERVENTIONAL". AND/OR/NOT join complete AREA[FieldName]value expressions; parentheses group them. Call clinicaltrials_get_field_definitions to find AREA[]-compatible field names.
includeUnknownEnrollment	boolean	optional	Include studies whose EnrollmentCount is the upstream "unknown" sentinel (99999999). Excluded by default — the sentinel pollutes RANGE[N, MAX] queries. Set true for data-quality audits.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "General free-text search across all fields. Runs the 57-field relevance search ClinicalTrials.gov publishes for this parameter — NCTId, NCTIdAlias, OrgStudyId, SecondaryId, Acronym, BriefTitle, OfficialTitle, Condition, InterventionName, InterventionOtherName, Phase, StdAge, StudyType, BriefSummary, outcome measures and their descriptions, LeadSponsorName, CollaboratorName, the Location* fields, the Design* fields, and the ConditionAncestorTerm/InterventionAncestorTerm MeSH umbrellas — so a hit need not carry your term in the field you had in mind. Plain words plus AND, OR, NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression — those work here as well as in advancedFilter, so AREA[Phase]PHASE2 is accepted in this parameter; a stray bracket fails. `( )` group sub-expressions and work when matched; `,` acts as AND. The dedicated *Query parameters (conditionQuery, interventionQuery, etc.) scope a search to one field.",
      "type": "string"
    },
    "conditionQuery": {
      "description": "Condition/disease-specific search. E.g., \"Type 2 Diabetes\", \"non-small cell lung cancer\". Matches Condition, BriefTitle, OfficialTitle, ConditionMeshTerm, ConditionAncestorTerm, Keyword, and NCTId. ConditionAncestorTerm is the MeSH umbrella above the conditions a study itself lists, so results run broader than those lists — a study can match a parent term it never names. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "interventionQuery": {
      "description": "Intervention/treatment search. E.g., \"pembrolizumab\", \"cognitive behavioral therapy\". Matches InterventionName, InterventionType, ArmGroupType, InterventionOtherName, BriefTitle, OfficialTitle, ArmGroupLabel, InterventionMeshTerm, Keyword, InterventionAncestorTerm, InterventionDescription, and ArmGroupDescription. InterventionAncestorTerm is the MeSH umbrella above the interventions a study itself lists, so results run broader than those lists. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "locationQuery": {
      "description": "Location search — city, state, country, or facility name. Matches LocationCity, LocationState, LocationCountry, LocationFacility, and LocationZip; a study matches when any of its sites does. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "sponsorQuery": {
      "description": "Sponsor/collaborator name search. Matches LeadSponsorName, CollaboratorName, and OrgFullName. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "titleQuery": {
      "description": "Search within study titles and acronyms only. Matches Acronym, BriefTitle, and OfficialTitle. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "outcomeQuery": {
      "description": "Search within outcome measure fields. Matches PrimaryOutcomeMeasure, SecondaryOutcomeMeasure, OtherOutcomeMeasure, and OutcomeMeasureTitle, plus their description counterparts PrimaryOutcomeDescription, SecondaryOutcomeDescription, OtherOutcomeDescription, OutcomeMeasureDescription, and OutcomeMeasurePopulationDescription — so a term appearing only in outcome prose still matches. Plain words plus AND/OR/NOT. `[ ]` are valid only inside an AREA[FieldName]value or RANGE[min, max] expression, which this parameter accepts; a stray bracket fails. `( )` group sub-expressions when matched; `,` acts as AND.",
      "type": "string"
    },
    "statusFilter": {
      "description": "Filter by study status. Omit to count all statuses — an empty list is rejected, not treated as \"no filter\". Values: RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION, SUSPENDED, TERMINATED, WITHDRAWN, UNKNOWN, WITHHELD, NO_LONGER_AVAILABLE, AVAILABLE, APPROVED_FOR_MARKETING, TEMPORARILY_NOT_AVAILABLE.",
      "anyOf": [
        {
          "type": "string",
          "description": "A single status value."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Multiple status values (OR)."
        }
      ]
    },
    "phaseFilter": {
      "description": "Filter by trial phase. Omit to count all phases — an empty list is rejected, not treated as \"no filter\". Values: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA.",
      "anyOf": [
        {
          "type": "string",
          "description": "A single phase value."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Multiple phase values (OR)."
        }
      ]
    },
    "advancedFilter": {
      "description": "Advanced filter using AREA[FieldName]value syntax. Examples: \"AREA[StudyType]INTERVENTIONAL\", \"AREA[EnrollmentCount]RANGE[100, 1000]\", \"AREA[Phase]PHASE2 AND AREA[StudyType]INTERVENTIONAL\", \"(AREA[Phase]PHASE3 OR AREA[Phase]PHASE4) AND AREA[StudyType]INTERVENTIONAL\". AND/OR/NOT join complete AREA[FieldName]value expressions; parentheses group them. Call clinicaltrials_get_field_definitions to find AREA[]-compatible field names.",
      "type": "string"
    },
    "includeUnknownEnrollment": {
      "default": false,
      "description": "Include studies whose EnrollmentCount is the upstream \"unknown\" sentinel (99999999). Excluded by default — the sentinel pollutes RANGE[N, MAX] queries. Set true for data-quality audits.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

clinicaltrials_get_field_values

Discover valid values for ClinicalTrials.gov fields with study counts per value. Use to explore available filter options before building a search — e.g., valid OverallStatus, Phase, InterventionType, StudyType, or LeadSponsorClass values.

Parameters1

fields

any

required

PascalCase field name(s) to get value statistics for — an empty list is rejected, not treated as "every field". Examples: OverallStatus, Phase, StudyType, Sex, LeadSponsorClass. Use clinicaltrials_get_field_definitions with a query to find more field names.

Raw schema

{
  "type": "object",
  "properties": {
    "fields": {
      "anyOf": [
        {
          "type": "string",
          "description": "A single PascalCase field name."
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Multiple PascalCase field names (at least one required)."
        }
      ],
      "description": "PascalCase field name(s) to get value statistics for — an empty list is rejected, not treated as \"every field\". Examples: OverallStatus, Phase, StudyType, Sex, LeadSponsorClass. Use clinicaltrials_get_field_definitions with a query to find more field names."
    }
  },
  "required": [
    "fields"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

clinicaltrials_get_field_definitions

Resolve valid field names from the ClinicalTrials.gov data model — the canonical PascalCase identifiers (OverallStatus, EnrollmentCount, LeadSponsorName) accepted by the `fields`, `advancedFilter`, and `sort` parameters of other tools, and as input to clinicaltrials_get_field_values. Select a mode: `"search"` — keyword search returning ranked matches (pass `query`, e.g. "enrollment", "sponsor", "adverse events"); `"drill"` — drill into a specific section by dot-notation path (pass `path`, e.g. "protocolSection.designModule"); `"overview"` — top-level summary of all sections (no additional args).

Parameters5

mode	string	required	Operation mode. "search" — keyword search (requires `query`); "drill" — drill into a section by path (requires `path`); "overview" — list all top-level sections (no other args needed).
query	string	optional	search mode only. Keyword to search field names by — e.g., "enrollment", "sponsor", "adverse events". Returns matching field names ranked by relevance with their full paths and data types.
path	string	optional	drill mode only. Dot-notation path to drill into — e.g., "protocolSection.designModule", "protocolSection.eligibilityModule", "resultsSection". Returns the section's individual fields.
limit	integer	optional	search mode only. Maximum results to return. Default: 20.
includeIndexedOnly	boolean	optional	drill mode only. Only return indexed (searchable) fields. Default: false.

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "search",
        "drill",
        "overview"
      ],
      "description": "Operation mode. \"search\" — keyword search (requires `query`); \"drill\" — drill into a section by path (requires `path`); \"overview\" — list all top-level sections (no other args needed)."
    },
    "query": {
      "description": "search mode only. Keyword to search field names by — e.g., \"enrollment\", \"sponsor\", \"adverse events\". Returns matching field names ranked by relevance with their full paths and data types.",
      "type": "string"
    },
    "path": {
      "description": "drill mode only. Dot-notation path to drill into — e.g., \"protocolSection.designModule\", \"protocolSection.eligibilityModule\", \"resultsSection\". Returns the section's individual fields.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "search mode only. Maximum results to return. Default: 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "includeIndexedOnly": {
      "description": "drill mode only. Only return indexed (searchable) fields. Default: false.",
      "type": "boolean"
    }
  },
  "required": [
    "mode"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

clinicaltrials_get_study_results

Fetch clinical trial results data from ClinicalTrials.gov for completed studies — outcome measures with statistics, adverse events, participant flow, baseline characteristics, and results metadata (limitations & caveats, certain-agreement disclosure restrictions, results point of contact). Only available for studies where hasResults is true. Use clinicaltrials_search_studies first to find studies with results. A results-rich record can exceed 500KB per study in full mode — bound it with summary=true, narrower sections, or the outcomeLimit / adverseEventLimit caps. A bounded list is resumable: outcomeOffset / seriousEventOffset / otherEventOffset start the next window, and each study's filtersApplied reports what was trimmed and the next offset for every list left short. A previous (alias) NCT ID resolves to its canonical study, named in canonicalNctId.

Parameters8

nctIds	any	required	One or more NCT IDs (max 20) — an empty list is rejected, and a repeated ID collapses to one results entry in first-occurrence order. E.g., "NCT12345678" or ["NCT12345678", "NCT87654321"]. Use summary=true for large batches to avoid large payloads.
sections	any	optional	Filter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline, moreInfo. Omit for all sections — an empty list is rejected, not treated as omission.
summary	boolean	optional	Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode typically cuts that to a few KB, scaling with the measure count rather than to a fixed ceiling. An outcome summary keeps the title, type, timeframe, paramType, dispersionType, unit, group/class counts, per-group denominators, one statistical analysis, and a top-line projection of a single class/category cell — labelled with the class and category titles it came from and a count of the siblings it omits. The measurements outside that cell and the remaining analyses are dropped; re-run with summary=false to reach them. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit.
outcomeLimit	integer	optional	Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure). Applies to full mode only — summary mode is already condensed. Each surviving measure keeps its complete groups/classes/measurements/analyses tree. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list.
adverseEventLimit	integer	optional	Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event). Applies to full mode only — summary mode already ranks the top 20 by participants affected. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list.
outcomeOffset	integer	optional	Optional index of the first outcome measure to return, in the order ClinicalTrials.gov publishes them. Omit or 0 to start at the first. Pair with outcomeLimit to page a long list: each response reports filtersApplied.nextOutcomeOffset for the study, and the list is exhausted when that field is absent. Applied to every study in the call. An offset at or past the end returns an empty list with filtersApplied.totalOutcomes stating the upstream length, not an error. Rejected with summary: true or when sections excludes outcomes.
seriousEventOffset	integer	optional	Optional index of the first serious adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of otherEventOffset — the two lists have uncorrelated lengths — and pairs with adverseEventLimit, which bounds each list separately. Continue from filtersApplied.nextSeriousEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.
otherEventOffset	integer	optional	Optional index of the first other (non-serious) adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of seriousEventOffset and pairs with adverseEventLimit. Continue from filtersApplied.nextOtherEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.

Raw schema

{
  "type": "object",
  "properties": {
    "nctIds": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^NCT\\d{8}$",
          "description": "A single NCT ID."
        },
        {
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^NCT\\d{8}$"
          },
          "description": "Multiple NCT IDs (max 20)."
        }
      ],
      "description": "One or more NCT IDs (max 20) — an empty list is rejected, and a repeated ID collapses to one results entry in first-occurrence order. E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."
    },
    "sections": {
      "description": "Filter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline, moreInfo. Omit for all sections — an empty list is rejected, not treated as omission.",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "outcomes",
            "adverseEvents",
            "participantFlow",
            "baseline",
            "moreInfo"
          ],
          "description": "A single section name."
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "outcomes",
              "adverseEvents",
              "participantFlow",
              "baseline",
              "moreInfo"
            ]
          },
          "description": "Multiple section names."
        }
      ]
    },
    "summary": {
      "default": false,
      "description": "Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode typically cuts that to a few KB, scaling with the measure count rather than to a fixed ceiling. An outcome summary keeps the title, type, timeframe, paramType, dispersionType, unit, group/class counts, per-group denominators, one statistical analysis, and a top-line projection of a single class/category cell — labelled with the class and category titles it came from and a count of the siblings it omits. The measurements outside that cell and the remaining analyses are dropped; re-run with summary=false to reach them. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit.",
      "type": "boolean"
    },
    "outcomeLimit": {
      "description": "Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure). Applies to full mode only — summary mode is already condensed. Each surviving measure keeps its complete groups/classes/measurements/analyses tree. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "adverseEventLimit": {
      "description": "Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event). Applies to full mode only — summary mode already ranks the top 20 by participants affected. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "outcomeOffset": {
      "description": "Optional index of the first outcome measure to return, in the order ClinicalTrials.gov publishes them. Omit or 0 to start at the first. Pair with outcomeLimit to page a long list: each response reports filtersApplied.nextOutcomeOffset for the study, and the list is exhausted when that field is absent. Applied to every study in the call. An offset at or past the end returns an empty list with filtersApplied.totalOutcomes stating the upstream length, not an error. Rejected with summary: true or when sections excludes outcomes.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "seriousEventOffset": {
      "description": "Optional index of the first serious adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of otherEventOffset — the two lists have uncorrelated lengths — and pairs with adverseEventLimit, which bounds each list separately. Continue from filtersApplied.nextSeriousEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "otherEventOffset": {
      "description": "Optional index of the first other (non-serious) adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of seriousEventOffset and pairs with adverseEventLimit. Continue from filtersApplied.nextOtherEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "nctIds"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

clinicaltrials_find_eligible

Match patient demographics and conditions to eligible recruiting clinical trials. Provide age, sex, conditions, and location to find studies with matching eligibility criteria, contact information, and recruiting locations. Results are re-ranked so studies whose own condition matches a requested condition surface above tangential matches from ClinicalTrials.gov's fuzzy condition search. Each candidate returns only the sites matching the requested location (capped by locationLimit), not the study's full registered site list — a large trial can register hundreds of sites worldwide. When none of a candidate's matched sites is recruiting, its nearest recruiting site is added, so an enrollable site is never hidden behind a closer closed one. Fetch a study's complete record with clinicaltrials_get_study_record.

Parameters8

age	integer	required	Patient age in years.
sex	string	required	Patient's biological sex. Use 'ALL' to include studies regardless of sex restrictions.
conditions	array	required	Medical conditions or diagnoses, e.g. ["Type 2 Diabetes", "Hypertension"]. Each entry is matched as a condition (multi-word entries match as a phrase); multiple entries are combined with OR, so studies for any listed condition qualify. Returned studies are re-ranked so those whose own condition list names a requested condition rank above tangential matches the upstream fuzzy search pulls in via the MeSH umbrella.
location	object	required	Patient location as `{ country (required), state?, city? }`. Country is required; state/city narrow the match. For radius-based geographic search, use clinicaltrials_search_studies with geoFilter.
healthyVolunteer	boolean	optional	Whether the patient is a healthy volunteer. When true, only studies accepting healthy volunteers are queried.
recruitingOnly	boolean	optional	Only include actively recruiting studies.
maxResults	integer	optional	Maximum results to return.
locationLimit	integer	optional	Cap on the sites returned per candidate. Each candidate keeps only the sites matching the requested location at the narrowest level that matched (city, else state, else country), capped at this many; the rest of the study's registered sites are omitted. The cap governs those matched sites — when none of them is recruiting, the candidate's nearest recruiting site is added on top of it, so a candidate can carry one site more than this. Raise it to see more nearby sites, or fetch the complete site list with clinicaltrials_get_study_record. Each candidate reports totalLocations / matchedLocations / locationsTruncated / nearestRecruitingSiteAdded in locationSummary only when the bound actually dropped sites.

Raw schema

{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Patient age in years."
    },
    "sex": {
      "type": "string",
      "enum": [
        "FEMALE",
        "MALE",
        "ALL"
      ],
      "description": "Patient's biological sex. Use 'ALL' to include studies regardless of sex restrictions."
    },
    "conditions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Medical conditions or diagnoses, e.g. [\"Type 2 Diabetes\", \"Hypertension\"]. Each entry is matched as a condition (multi-word entries match as a phrase); multiple entries are combined with OR, so studies for any listed condition qualify. Returned studies are re-ranked so those whose own condition list names a requested condition rank above tangential matches the upstream fuzzy search pulls in via the MeSH umbrella."
    },
    "location": {
      "type": "object",
      "properties": {
        "country": {
          "type": "string",
          "description": "Country name. E.g., \"United States\"."
        },
        "state": {
          "description": "State or province.",
          "type": "string"
        },
        "city": {
          "description": "City name.",
          "type": "string"
        }
      },
      "required": [
        "country"
      ],
      "additionalProperties": false,
      "description": "Patient location as `{ country (required), state?, city? }`. Country is required; state/city narrow the match. For radius-based geographic search, use clinicaltrials_search_studies with geoFilter."
    },
    "healthyVolunteer": {
      "default": false,
      "description": "Whether the patient is a healthy volunteer. When true, only studies accepting healthy volunteers are queried.",
      "type": "boolean"
    },
    "recruitingOnly": {
      "default": true,
      "description": "Only include actively recruiting studies.",
      "type": "boolean"
    },
    "maxResults": {
      "default": 10,
      "description": "Maximum results to return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "locationLimit": {
      "default": 10,
      "description": "Cap on the sites returned per candidate. Each candidate keeps only the sites matching the requested location at the narrowest level that matched (city, else state, else country), capped at this many; the rest of the study's registered sites are omitted. The cap governs those matched sites — when none of them is recruiting, the candidate's nearest recruiting site is added on top of it, so a candidate can carry one site more than this. Raise it to see more nearby sites, or fetch the complete site list with clinicaltrials_get_study_record. Each candidate reports totalLocations / matchedLocations / locationsTruncated / nearestRecruitingSiteAdded in locationSummary only when the bound actually dropped sites.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "age",
    "sex",
    "conditions",
    "location"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md16 KBView on GitHub

clinicaltrialsgov-mcp-server

Search ClinicalTrials.gov trials, retrieve study details and results, and match patients to eligible trials via MCP. STDIO or Streamable HTTP.

7 Tools • 1 Resource • 1 Prompt

Version MCP SDK TypeScript

Public Hosted Server: https://clinicaltrials.caseyjhand.com/mcp

Overview

Clinical trial data from the ClinicalTrials.gov REST API v2 — the US National Library of Medicine's registry of ~577K clinical trial studies. Search trials, fetch full study records and posted results, discover field names and valid values, and match patient demographics to eligible recruiting trials. Public, read-only, no authentication required. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`clinicaltrials_search_studies`	Search studies with full-text and field-specific queries, status/phase/geographic filters, pagination, sorting, and field selection
`clinicaltrials_get_study_record`	Fetch a single study by NCT ID — full protocol record with optional location/outcome/reference caps
`clinicaltrials_get_study_count`	Fast total study count for a query, without fetching data
`clinicaltrials_get_field_values`	Discover valid values for API fields, with per-value study counts
`clinicaltrials_get_field_definitions`	Resolve valid field names — keyword search, path drill-down, or top-level overview
`clinicaltrials_get_study_results`	Fetch posted results — outcomes, adverse events, participant flow, baseline — for completed studies
`clinicaltrials_find_eligible`	Match patient demographics and conditions to eligible recruiting trials

Resources

Resource	Description
`clinicaltrials://{nctId}`	Fetch a single clinical study by NCT ID as JSON, with capped lists and results replaced by counts

Prompts

Prompt	Description
`analyze_trial_landscape`	Guides a data-driven clinical trial landscape analysis using the count and search tools

Capability reference

`clinicaltrials_search_studies` _tool

Free-text query plus field-specific conditionQuery / interventionQuery / locationQuery / sponsorQuery / titleQuery / outcomeQuery; statusFilter / phaseFilter enums, advancedFilter (AREA[FieldName]value / RANGE[min, max] syntax), and geoFilter (distance(lat,lon,radius) with a mi/km suffix) for proximity search with nearest-site re-ranking
Returns a compact per-study index by default (nctId, briefTitle, overallStatus, phases, enrollmentCount, leadSponsor, conditions, a bounded locations summary); pass fields (PascalCase leaves) for a full-fidelity projection — full records run ~70KB
pageSize 1–CT_MAX_PAGE_SIZE (default 200), cursor pagination via pageToken, sort on up to 2 fields
Excludes the upstream "unknown" enrollment sentinel (99999999) by default — includeUnknownEnrollment to include it, or automatically lifted when nctIds is supplied
Typed errors: blank_value, ids_not_found, field_invalid, enum_invalid, query_parse_error, geo_invalid, sort_invalid, rate_limited

`clinicaltrials_get_study_record` _tool

Full protocol record by NCT ID — identification, status, sponsor, conditions, design, arms/interventions, outcomes, eligibility, contacts/locations
Optional locationLimit (≤500), outcomeLimit / referenceLimit (≤100), and nearLocation (lat, lon, radiusMi default 50) to bound and sort locations; upstream totals reported in filtersApplied only when a cap actually trims the list
resultsSection is replaced by compact resultsSummary counts — fetch full results via clinicaltrials_get_study_results
Typed errors: study_not_found, rate_limited

`clinicaltrials_get_study_count` _tool

Same query/filter surface as clinicaltrials_search_studies (free-text and field-specific queries, status/phase filters, advancedFilter) but returns only totalCount — no study data fetched
Excludes the unknown-enrollment sentinel by default (includeUnknownEnrollment to include it)
Typed errors: blank_value, field_invalid, enum_invalid, query_parse_error, rate_limited

`clinicaltrials_get_field_values` _tool

One or more PascalCase field names (e.g. OverallStatus, Phase, LeadSponsorClass) — returns each field's type, unique-value count, and top values with study counts (capped at 250 by the API)
Numeric/date fields report min / max / avg / formats instead of top values; boolean fields report trueCount / falseCount
multiValued flags fields where a study can carry several values, so per-value study counts can sum above the study total
Typed errors: blank_value, field_invalid, rate_limited

`clinicaltrials_get_field_definitions` _tool

Three modes: search (keyword, ranked matches, limit up to 100, default 20), drill (dot-notation path into a section), overview (top-level sections, no other args)
Resolves the canonical PascalCase field names accepted by fields, advancedFilter, sort, and clinicaltrials_get_field_values
Typed errors: blank_value, mode_mismatch, mode_requires, path_not_found, rate_limited

`clinicaltrials_get_study_results` _tool

Up to 20 NCT IDs per call; only returns data for studies where hasResults is true — outcome measures, adverse events, participant flow, baseline characteristics, and results metadata
summary (default false) condenses a full result set — which can exceed 500KB per study — to a few KB; full mode supports outcomeLimit (≤100) and adverseEventLimit (≤500), resumable via outcomeOffset / seriousEventOffset / otherEventOffset
sections filters to outcomes, adverseEvents, participantFlow, baseline, moreInfo
A previous (alias) NCT ID resolves to its canonical study, named in canonicalNctId
Typed errors: blank_value, offset_not_applicable, rate_limited

`clinicaltrials_find_eligible` _tool

Takes age, sex (FEMALE / MALE / ALL), conditions[], location (country required, state / city optional), healthyVolunteer, recruitingOnly (default true), maxResults (≤50)
Re-ranks results so studies whose own condition list names a requested condition surface above tangential MeSH-umbrella matches from the upstream fuzzy search
Bounds each candidate's locations to the sites matching the requested location (capped by locationLimit, ≤500) instead of every registered site, adding the nearest recruiting site when none of the matched ones is open
funnel reports match counts at each filter stage (condition → +location → +demographics) to show where the query narrowed to zero
Typed errors: blank_value, rate_limited

`clinicaltrials://{nctId}` _resource

Full protocol record as application/json, with locations, secondary/other outcomes, and references each capped at 50 — fixed server-side, no arguments
Results data is replaced by resultsSummary counts; truncated and filtersApplied disclose what was capped, with retrieval naming the tools that fetch the full data
Typed errors: study_not_found, rate_limited

`analyze_trial_landscape` _prompt

Arguments: topic required; focusAreas (comma-separated) optional
Returns one user message pointing the agent at the count, search, field-discovery, and results tools for a data-driven landscape analysis

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

ClinicalTrials.gov-specific:

Type-safe client for the ClinicalTrials.gov REST API v2 — public, no authentication or API keys required
Serialized request queue enforcing ClinicalTrials.gov's ~1 req/sec rate limit, with retry and exponential backoff on 429/5xx responses
Auto-corrects field names passed to fields/sort — case/whitespace fixes and known legacy aliases (e.g. RecruitmentStatus → OverallStatus) — before validating, logging every correction
Detects upstream HTML error pages returned with a JSON content-type and retries rather than parsing them as data
Geographic proximity search and nearest-site re-ranking, with no geocoding dependency

Agent-friendly output:

Provenance — clinicaltrials_search_studies / clinicaltrials_get_study_count / clinicaltrials_find_eligible echo searchCriteria on every call, including sentinelFilterActive when the default unknown-enrollment exclusion applies, and clinicaltrials_get_study_results names canonicalNctId when a previous (alias) ID resolves to a different study
Graceful partial failure — clinicaltrials_get_study_results returns per-study fetchErrors / studiesWithoutResults rows instead of failing the whole batch when one ID is malformed or lacks results
Discriminated output — typed error reason codes per tool (study_not_found, blank_value, offset_not_applicable, …), and bounded lists (filtersApplied, locationSummary) carry a next*Offset only when more remains, so callers branch on presence instead of parsing text
Response shaping — clinicaltrials_search_studies and clinicaltrials_find_eligible return a compact per-study index or location-bounded set by default instead of the ~70KB full record, escalating to full fidelity only via fields or clinicaltrials_get_study_record

Getting started

Public Hosted Instance

A public instance is available at https://clinicaltrials.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "streamable-http",
      "url": "https://clinicaltrials.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/clinicaltrialsgov-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).

Installation

Clone the repository:

git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git

Navigate into the directory:

cd clinicaltrialsgov-mcp-server

Install dependencies:

bun install

Configuration

All configuration is optional — the server works with defaults and no API keys.

Variable	Description	Default
`CT_API_BASE_URL`	ClinicalTrials.gov API base URL.	`https://clinicaltrials.gov/api/v2`
`CT_REQUEST_TIMEOUT_MS`	Per-request timeout in milliseconds.	`30000`
`CT_MAX_PAGE_SIZE`	Maximum page size cap.	`200`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_SESSION_MODE`	HTTP session mode: `stateless`, `stateful`, or `auto`.	`stateless`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`OTEL_ENABLED`	Enable OpenTelemetry tracing.	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, and security audit
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t clinicaltrialsgov-mcp-server .
docker run --rm -p 3010:3010 clinicaltrialsgov-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/clinicaltrialsgov-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources/prompts and inits the ClinicalTrials.gov service.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`).
`src/mcp-server/prompts`	Prompt definitions (`*.prompt.ts`).
`src/services/clinical-trials`	ClinicalTrials.gov REST API v2 client — retry, rate limiting, field search, types.
`tests/`	Unit and integration tests.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, no console calls
Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
Validate raw API responses, normalize to domain types, and never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (7)

clinicaltrials_search_studiesclinicaltrials_get_study_recordclinicaltrials_get_study_countclinicaltrials_get_field_valuesclinicaltrials_get_field_definitionsclinicaltrials_get_study_resultsclinicaltrials_find_eligible

Configuration

Environment variables

CT_API_BASE_URLdefault https://clinicaltrials.gov/api/v2

ClinicalTrials.gov API base URL.

CT_REQUEST_TIMEOUT_MSdefault 30000

Per-request timeout in milliseconds.

CT_MAX_PAGE_SIZEdefault 200

Maximum page size cap.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "clinicaltrialsgov-mcp-server@2.9.8",
        "run",
        "start:stdio"
      ],
      "env": {
        "CT_API_BASE_URL": "https://clinicaltrials.gov/api/v2",
        "CT_REQUEST_TIMEOUT_MS": "30000",
        "CT_MAX_PAGE_SIZE": "200",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

io.github.cyanheads/clinicaltrialsgov-mcp-server (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

clinicaltrials_search_studies

clinicaltrials_get_study_record

clinicaltrials_get_study_count

clinicaltrials_get_field_values

clinicaltrials_get_field_definitions

clinicaltrials_get_study_results

clinicaltrials_find_eligible

clinicaltrialsgov-mcp-server

Overview

Tools

Resources

Prompts

Capability reference

clinicaltrials_search_studies tool

clinicaltrials_get_study_record tool

clinicaltrials_get_study_count tool

clinicaltrials_get_field_values tool

clinicaltrials_get_field_definitions tool

clinicaltrials_get_study_results tool

clinicaltrials_find_eligible tool

clinicaltrials://{nctId} resource

analyze_trial_landscape prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`clinicaltrials_search_studies` _tool

`clinicaltrials_get_study_record` _tool

`clinicaltrials_get_study_count` _tool

`clinicaltrials_get_field_values` _tool

`clinicaltrials_get_field_definitions` _tool

`clinicaltrials_get_study_results` _tool

`clinicaltrials_find_eligible` _tool

`clinicaltrials://{nctId}` _resource

`analyze_trial_landscape` _prompt