io.github.cyanheads/openfda-mcp-server

Official14 toolsLive

by cyanheads · TypeScript

Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.

This MCP server queries FDA data covering drugs, food, devices, and recalls by using openFDA. It provides access over either STDIO or Streamable HTTP. The repository is published as @cyanheads/openfda-mcp-server, with a stated tool set totaling 14 tools.

🛠️ Key Features

Queries FDA data via openFDA
Covers drugs, food, devices, and recalls
Supports two transport modes: STDIO and Streamable HTTP
14 tools

🚀 Use Cases

Retrieving FDA-related records for the listed domains
Integrating openFDA queries into Model Context Protocol workflows

⚡ Developer Benefits

MCP server compatibility with Model Context Protocol
Developer-oriented TypeScript project (topic listed)
Discoverable tool count (14) for planning integrations

⚠️ Limitations

Scope is limited to FDA data categories stated: drugs, food, devices, and recalls
Integration requires using STDIO or Streamable HTTP (as described)

Topics

adverse-eventsdrug-safetyfdamcpmcp-servermodel-context-protocolopenfdatypescriptcyanheads

Captured live from the server via tools/list.

openfda_search_adverse_events

Search adverse event reports across drugs, food, and devices. Use to investigate safety signals, find reports for a specific product, or explore reactions by demographics. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters7

category	string	required	Product category — each has different field schemas in the response
search	string	optional	openFDA search query. Examples: patient.drug.medicinalproduct:"aspirin", patient.reaction.reactionmeddrapt:"nausea" AND serious:"1". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. Sortable date fields are category-specific: drug → receivedate:desc (or receiptdate), food → date_created:desc (or date_started), device → date_received:desc (or date_of_event). A field from another category (e.g. receivedate on food or device) causes a query error — use the field for this category.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. Drug reports are by far the largest — a single drug/event report averages tens of kilobytes where a food/event report is a few hundred bytes.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "drug",
        "food",
        "device"
      ],
      "description": "Product category — each has different field schemas in the response"
    },
    "search": {
      "description": "openFDA search query. Examples: patient.drug.medicinalproduct:\"aspirin\", patient.reaction.reactionmeddrapt:\"nausea\" AND serious:\"1\". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. Sortable date fields are category-specific: drug → receivedate:desc (or receiptdate), food → date_created:desc (or date_started), device → date_received:desc (or date_of_event). A field from another category (e.g. receivedate on food or device) causes a query error — use the field for this category.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. Drug reports are by far the largest — a single drug/event report averages tens of kilobytes where a food/event report is a few hundred bytes.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "category"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_search_animal_events

Search adverse event reports for veterinary drugs and devices submitted to the FDA Center for Veterinary Medicine. Records include animal species, breed, age, weight, drug name and route, adverse reactions (using VeDDRA terminology), and outcome. Use to investigate safety signals for veterinary products, find reports by animal species or drug, or explore reaction patterns. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters6

search	string	optional	openFDA search query using field:value syntax. Examples: animal.species:"Dog", drug.brand_name:"Bravecto", reaction.veddra_term_name:"Vomiting", serious_ae:"true". Omit to browse recent reports. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: original_receive_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "description": "openFDA search query using field:value syntax. Examples: animal.species:\"Dog\", drug.brand_name:\"Bravecto\", reaction.veddra_term_name:\"Vomiting\", serious_ae:\"true\". Omit to browse recent reports. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: original_receive_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_search_drug_shortages

Search FDA drug shortage records. Returns per-product shortage status, availability, therapeutic category, dosage form, manufacturer, and dates. Use to check whether a drug is currently in shortage, find all oncology drugs with supply issues, or retrieve the openfda block (brand_name, product_ndc, rxcui) to chain into openfda_get_drug_label or openfda_lookup_ndc. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters6

search	string	optional	openFDA search query using field:value syntax. Examples: status:"Current", therapeutic_category:"Oncology", generic_name:"carboplatin", company_name:"pfizer". Omit to browse all records. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request. Call openfda_describe_fields({ endpoint: "drug/shortages" }) for the complete field list.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: update_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "description": "openFDA search query using field:value syntax. Examples: status:\"Current\", therapeutic_category:\"Oncology\", generic_name:\"carboplatin\", company_name:\"pfizer\". Omit to browse all records. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request. Call openfda_describe_fields({ endpoint: \"drug/shortages\" }) for the complete field list.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: update_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_search_recalls

Search enforcement reports and recall actions across drugs, food, and devices. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters8

category	string	required	Product category
endpoint	string	optional	Report type. Default enforcement. The recall endpoint is only available for devices.
search	string	optional	openFDA search query. Examples: classification:"Class I" (also "Class II" or "Class III"), recalling_firm:"pfizer", reason_for_recall:"undeclared allergen". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort (e.g. report_date:desc,status.exact:asc). Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. Device records are the largest here — a device enforcement or recall record runs several kilobytes where a drug or food enforcement record is around one.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "drug",
        "food",
        "device"
      ],
      "description": "Product category"
    },
    "endpoint": {
      "default": "enforcement",
      "description": "Report type. Default enforcement. The recall endpoint is only available for devices.",
      "type": "string",
      "enum": [
        "enforcement",
        "recall"
      ]
    },
    "search": {
      "description": "openFDA search query. Examples: classification:\"Class I\" (also \"Class II\" or \"Class III\"), recalling_firm:\"pfizer\", reason_for_recall:\"undeclared allergen\". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort (e.g. report_date:desc,status.exact:asc). Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. Device records are the largest here — a device enforcement or recall record runs several kilobytes where a drug or food enforcement record is around one.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "category"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_search_tobacco_reports

Search problem reports submitted to the FDA for tobacco products, including e-cigarettes, vaping products, cigarettes, and smokeless tobacco. Reports capture product type, reported health problems (e.g. seizure, chest pain), product problems (e.g. exploding battery), whether a non-user was affected, and submission date. Use to investigate safety signals, find reports by product type, or analyze health effects. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters6

search	string	optional	openFDA search query using field:value syntax. Examples: tobacco_products:"Electronic cigarette", reported_health_problems:"Seizure", nonuser_affected:"Yes". Omit to browse recent reports. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: date_submitted:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "description": "openFDA search query using field:value syntax. Examples: tobacco_products:\"Electronic cigarette\", reported_health_problems:\"Seizure\", nonuser_affected:\"Yes\". Omit to browse recent reports. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: date_submitted:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_count_values

Aggregate and tally unique values for any field across any openFDA endpoint. Returns ranked term-count pairs sorted by count descending. Pair with openfda_search_adverse_events, openfda_search_drug_approvals, openfda_search_device_clearances, openfda_search_recalls, openfda_get_drug_label, or openfda_lookup_ndc when sample records help interpret the aggregates.

Parameters4

endpoint	string	required	Full openFDA endpoint path (e.g. "drug/event", "device/classification")
count	string	required	Field to count. openfda_describe_fields gives the verified expression per field as countAs (null = not countable in any form). Otherwise: append .exact for whole-phrase counting of free-text fields (e.g. "patient.reaction.reactionmeddrapt.exact"); count identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) bare — .exact on those is rejected as not countable.
search	string	optional	Filter query to scope the count (e.g. patient.drug.medicinalproduct:"metformin"). Omit to count across every record in the endpoint. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
limit	number	optional	Number of top terms to return (default 100, max 1000 — openFDA's own count maximum). truncated reports whether more distinct terms exist beyond it, except at the maximum itself, where openFDA offers no way to tell.

Raw schema

{
  "type": "object",
  "properties": {
    "endpoint": {
      "type": "string",
      "enum": [
        "drug/event",
        "drug/label",
        "drug/enforcement",
        "drug/ndc",
        "drug/drugsfda",
        "drug/shortages",
        "food/event",
        "food/enforcement",
        "device/event",
        "device/510k",
        "device/pma",
        "device/recall",
        "device/enforcement",
        "device/classification",
        "device/registrationlisting",
        "device/udi",
        "device/covid19serology",
        "animalandveterinary/event",
        "tobacco/problem",
        "other/substance"
      ],
      "description": "Full openFDA endpoint path (e.g. \"drug/event\", \"device/classification\")"
    },
    "count": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "Field to count. openfda_describe_fields gives the verified expression per field as countAs (null = not countable in any form). Otherwise: append .exact for whole-phrase counting of free-text fields (e.g. \"patient.reaction.reactionmeddrapt.exact\"); count identifier fields openFDA already indexes as keywords (product_ndc, application_number, pma_number) bare — .exact on those is rejected as not countable."
    },
    "search": {
      "description": "Filter query to scope the count (e.g. patient.drug.medicinalproduct:\"metformin\"). Omit to count across every record in the endpoint. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "limit": {
      "default": 100,
      "description": "Number of top terms to return (default 100, max 1000 — openFDA's own count maximum). truncated reports whether more distinct terms exist beyond it, except at the maximum itself, where openFDA offers no way to tell.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "endpoint",
    "count"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_describe_fields

Return the searchable field paths for an openFDA endpoint, grouped by category with type and description. Use before constructing a search query to find the correct dotted field path — field names differ per endpoint and are not discoverable from the tool schema alone.

Parameters1

endpoint

string

required

openFDA endpoint to describe (e.g. "drug/event", "drug/shortages", "device/510k"). Must be one of the cataloged endpoints.

Raw schema

{
  "type": "object",
  "properties": {
    "endpoint": {
      "type": "string",
      "enum": [
        "drug/event",
        "drug/label",
        "drug/enforcement",
        "drug/ndc",
        "drug/drugsfda",
        "drug/shortages",
        "food/event",
        "food/enforcement",
        "device/event",
        "device/510k",
        "device/pma",
        "device/recall",
        "device/enforcement",
        "device/classification",
        "device/registrationlisting",
        "device/udi",
        "device/covid19serology",
        "animalandveterinary/event",
        "tobacco/problem",
        "other/substance"
      ],
      "description": "openFDA endpoint to describe (e.g. \"drug/event\", \"drug/shortages\", \"device/510k\"). Must be one of the cataloged endpoints."
    }
  },
  "required": [
    "endpoint"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_get_drug_label

Look up FDA drug labeling (package inserts / SPL documents). Check indications, warnings, dosage, contraindications, active ingredients, or any structured label section. A label runs to tens of thousands of tokens, so a page that exceeds the inline budget returns the list of available sections instead; re-call with sections to pull the ones you need.

Parameters5

search	string	required	Query targeting label fields. Examples: openfda.brand_name:"aspirin", openfda.generic_name:"metformin", openfda.manufacturer_name:"pfizer". For a specific revision, pass set_id with the SPL UUID returned in earlier results. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: effective_time:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of results to return (1-1000). Default 5. Labels are large, and the cost of a sections selection is the section summed across every record on the page — so it scales with this limit. Lower it before widening a selection.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
sections	array	optional	Label sections to return, e.g. ["boxed_warning","indications_and_usage"]. Names come from the outline an oversized page returns, or from openfda_describe_fields. Omit for the whole label — which returns the section outline instead when the page exceeds the inline size budget; an empty list is treated as omitted. A selection is returned whole even when it exceeds that budget, with its serialized size reported on the notice; the outline names a section measured to fit at the requested limit. Sections ending in _table hold SPL table markup: raw in structured results, rendered as Markdown tables in the text output. Metadata (openfda, set_id, id, effective_time, version) is returned either way and counts toward the size.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "Query targeting label fields. Examples: openfda.brand_name:\"aspirin\", openfda.generic_name:\"metformin\", openfda.manufacturer_name:\"pfizer\". For a specific revision, pass set_id with the SPL UUID returned in earlier results. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request."
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: effective_time:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 5,
      "description": "Maximum number of results to return (1-1000). Default 5. Labels are large, and the cost of a sections selection is the section summed across every record on the page — so it scales with this limit. Lower it before widening a selection.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "sections": {
      "description": "Label sections to return, e.g. [\"boxed_warning\",\"indications_and_usage\"]. Names come from the outline an oversized page returns, or from openfda_describe_fields. Omit for the whole label — which returns the section outline instead when the page exceeds the inline size budget; an empty list is treated as omitted. A selection is returned whole even when it exceeds that budget, with its serialized size reported on the notice; the outline names a section measured to fit at the requested limit. Sections ending in _table hold SPL table markup: raw in structured results, rendered as Markdown tables in the text output. Metadata (openfda, set_id, id, effective_time, version) is returned either way and counts toward the size.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "pattern": "\\S",
        "description": "A top-level label section name."
      }
    }
  },
  "required": [
    "search"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_search_drug_approvals

Search the Drugs@FDA database for drug application approvals (NDAs and ANDAs). Returns application details, sponsor info, and full submission history. Pair with openfda_get_drug_label to read the approved label, or openfda_count_values to aggregate by sponsor_name, product_type, or route. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters6

search	string	optional	openFDA search query. Examples: openfda.brand_name:"humira", sponsor_name:"PFIZER", submissions.submission_type:"ORIG" AND submissions.review_priority:"PRIORITY". Exact quoted values can be case-sensitive on some fields — sponsor_name is stored uppercase, so use sponsor_name:"PFIZER" (a lowercase quoted value returns no matches). Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: submissions.submission_status_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. A record carries its application's whole submission history, so a long-running application is an order of magnitude larger than a recent one.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "description": "openFDA search query. Examples: openfda.brand_name:\"humira\", sponsor_name:\"PFIZER\", submissions.submission_type:\"ORIG\" AND submissions.review_priority:\"PRIORITY\". Exact quoted values can be case-sensitive on some fields — sponsor_name is stored uppercase, so use sponsor_name:\"PFIZER\" (a lowercase quoted value returns no matches). Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: submissions.submission_status_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. A record carries its application's whole submission history, so a long-running application is an order of magnitude larger than a recent one.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_search_device_clearances

Search FDA device premarket notifications — 510(k) clearances and PMA approvals. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters7

pathway	string	required	Premarket pathway. 510(k) is the most common; PMA is for higher-risk devices.
search	string	optional	openFDA search query. Examples: applicant:"medtronic", advisory_committee_description:"cardiovascular", product_code:"DXN", openfda.device_name:"catheter". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: decision_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. A 510(k) record carries a summary narrative and is several times the size of a PMA record.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "pathway": {
      "type": "string",
      "enum": [
        "510k",
        "pma"
      ],
      "description": "Premarket pathway. 510(k) is the most common; PMA is for higher-risk devices."
    },
    "search": {
      "description": "openFDA search query. Examples: applicant:\"medtronic\", advisory_committee_description:\"cardiovascular\", product_code:\"DXN\", openfda.device_name:\"catheter\". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.",
      "type": "string",
      "minLength": 1,
      "pattern": "\\S"
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: decision_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. A 510(k) record carries a summary narrative and is several times the size of a PMA record.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "pathway"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_lookup_ndc

Look up drugs in the NDC (National Drug Code) Directory. Identify drug products by NDC code, find active ingredients, packaging details, or manufacturer info. Pair with openfda_get_drug_label using the returned brand_name or set_id to read the package insert. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.

Parameters6

search	string	required	openFDA search query. Examples: product_ndc:"0363-0218", brand_name:"aspirin", generic_name:"metformin", openfda.manufacturer_name:"walgreen", active_ingredients.name:"ASPIRIN". Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request.
sort	string	optional	Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: listing_expiration_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.
limit	number	optional	Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. A record grows with its packaging list, so a product with many package configurations is several times the size of one with a single package.
skip	number	optional	Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error.
stage	boolean	optional	Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.
canvas_id	string	optional	Canvas ID returned by a prior stage=true call to this tool or an openFDA search tool (openfda_search_*). Passing one stages this lookup onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "openFDA search query. Examples: product_ndc:\"0363-0218\", brand_name:\"aspirin\", generic_name:\"metformin\", openfda.manufacturer_name:\"walgreen\", active_ingredients.name:\"ASPIRIN\". Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request."
    },
    "sort": {
      "description": "Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Example: listing_expiration_date:desc. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name.",
      "type": "string",
      "minLength": 1,
      "pattern": "^ *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?(?: *, *[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*(?::[^,:]*)?)* *$"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. A record grows with its packaging list, so a product with many package configurations is several times the size of one with a single package.",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "skip": {
      "default": 0,
      "type": "number",
      "minimum": 0,
      "description": "Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error."
    },
    "stage": {
      "default": false,
      "description": "Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb.",
      "type": "boolean"
    },
    "canvas_id": {
      "description": "Canvas ID returned by a prior stage=true call to this tool or an openFDA search tool (openfda_search_*). Passing one stages this lookup onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "search"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_drug_profile

Resolve one drug name to its FDA identity, then fan out in parallel across the bounded per-drug openFDA endpoints and merge into one profile: identity, label highlights, adverse-event summary, recall history, Drugs@FDA approval, and shortage status. Replaces chaining openfda_get_drug_label, openfda_search_adverse_events, openfda_search_recalls, openfda_search_drug_approvals, and openfda_search_drug_shortages — and reconciles the identifier drift between endpoints that makes that chaining error-prone. Each section is best-effort: a miss returns null rather than failing the call. For deep dives into any one area, use the dedicated tool.

Parameters1

drug

string

required

Drug name to profile — brand or generic (e.g. "metformin", "Humira", "Glucophage"). Resolved once to canonical FDA identifiers, which then key every sub-query.

Raw schema

{
  "type": "object",
  "properties": {
    "drug": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "Drug name to profile — brand or generic (e.g. \"metformin\", \"Humira\", \"Glucophage\"). Resolved once to canonical FDA identifiers, which then key every sub-query."
    }
  },
  "required": [
    "drug"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_dataframe_describe

List the tables and column schemas on a DataCanvas staged by an openFDA search tool. Call before openfda_dataframe_query to discover the exact table name, column names, and DuckDB types needed for valid SQL. row_count is the full staged result set, not the inline preview count. Columns typed JSON hold nested openFDA objects/arrays — query them with DuckDB json functions.

Parameters1

canvas_id

string

required

Canvas ID from the canvas_id field of an openFDA search tool response (openfda_search_* or openfda_lookup_ndc), present when the search ran with stage=true.

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID from the canvas_id field of an openFDA search tool response (openfda_search_* or openfda_lookup_ndc), present when the search ran with stage=true."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openfda_dataframe_query

Run a read-only SQL SELECT against a DataCanvas table staged by an openFDA search tool (call one with stage=true; its response carries canvas_id + canvas_table). Enables GROUP BY, COUNT/SUM/AVG, time-series, and joins across the staged result set without re-paging the API. Call openfda_dataframe_describe first to get the exact table and column names. Results are capped at the canvas row limit — when truncated is true, page the rest with ORDER BY plus LIMIT/OFFSET. Scalar fields are stored as text (CAST for numeric math); nested objects/arrays are JSON columns — read them with DuckDB json functions, e.g. json_extract_string(openfda, '$.brand_name[0]'). Only SELECT is allowed — DDL, DML, COPY, and file-reading functions are blocked.

Parameters2

canvas_id	string	required	Canvas ID from the canvas_id field of an openFDA search tool response (openfda_search_* or openfda_lookup_ndc), present when the search ran with stage=true.
query	string	required	SQL SELECT against the staged table. Use the table name from openfda_dataframe_describe. Example: "SELECT classification, COUNT(*) AS n FROM spilled_ab12cd34 GROUP BY classification ORDER BY n DESC".

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID from the canvas_id field of an openFDA search tool response (openfda_search_* or openfda_lookup_ndc), present when the search ran with stage=true."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "SQL SELECT against the staged table. Use the table name from openfda_dataframe_describe. Example: \"SELECT classification, COUNT(*) AS n FROM spilled_ab12cd34 GROUP BY classification ORDER BY n DESC\"."
    }
  },
  "required": [
    "canvas_id",
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md25 KBView on GitHub

@cyanheads/openfda-mcp-server

Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.

14 Tools

Version MCP SDK TypeScript

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

Overview

FDA data on drugs, food, devices, and recalls from the openFDA public API. Search adverse events, recalls, drug approvals, and device clearances; look up NDC codes and drug labels; aggregate field counts across any endpoint. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`openfda_drug_profile`	One drug name → consolidated FDA profile: identity, label, adverse events, recalls, approval, shortage
`openfda_search_adverse_events`	Search adverse event reports across drugs, food, and devices
`openfda_search_animal_events`	Search adverse event reports for veterinary drugs and devices
`openfda_search_drug_shortages`	Search FDA drug shortage records — status, availability, therapeutic category, manufacturer
`openfda_search_tobacco_reports`	Search problem reports for tobacco products, e-cigarettes, and vaping devices
`openfda_search_recalls`	Search enforcement reports and recall actions across drugs, food, and devices
`openfda_count_values`	Aggregate and tally unique values for any field across any openFDA endpoint
`openfda_describe_fields`	Return searchable field paths for an openFDA endpoint, grouped by category
`openfda_get_drug_label`	Look up FDA drug labeling (package inserts / SPL documents)
`openfda_search_drug_approvals`	Search the Drugs@FDA database for NDA/ANDA application approvals
`openfda_search_device_clearances`	Search FDA device premarket notifications — 510(k) clearances and PMA approvals
`openfda_lookup_ndc`	Look up drugs in the NDC (National Drug Code) Directory
`openfda_dataframe_query`	Run read-only SQL over a result set staged on a DataCanvas (opt-in)
`openfda_dataframe_describe`	List tables and column schemas staged on a DataCanvas (opt-in)

Capability reference

`openfda_drug_profile` _tool

Resolves a brand or generic drug name to canonical FDA identifiers (generic name, NDC, RxCUI, SPL set ID) once, then keys every sub-query off that identity — avoids the identifier drift that breaks naive tool chaining
Fans out in parallel across drug/label, drug/event, drug/enforcement, drug/drugsfda, and drug/shortages; each section (label, adverse_events, recalls, approval, shortage) is best-effort and returns null on a miss rather than failing the call
A single-drug query resolves only to a single-ingredient product, never a combination
degraded[] names any section whose sub-query failed upstream (rate limit, 5xx, query error) — a section listed there is unknown, not confirmed absent
Auth, configuration, and cancellation failures abort the whole call rather than degrading silently
Accepts drug_name or name in place of drug

`openfda_search_adverse_events` _tool

category selects drug, food, or device — each returns a different field schema
limit up to 1000 and skip up to openFDA's 25000-record ceiling (past it: typed pagination_limit_reached); the page is also bounded by a shared ~24 KB serialized-byte budget — drug/event reports run tens of KB each against a few hundred bytes for food/event, so an oversized page returns fewer records than requested and reports the cut via page_omitted
Sortable date field is category-specific (receivedate for drug, date_created for food, date_received for device) — a field from another category causes a query error
Optional stage: true (or canvas_id) drains the matched set onto a DataCanvas table for SQL via openfda_dataframe_query

`openfda_search_animal_events` _tool

Covers FDA Center for Veterinary Medicine reports — animal species/breed/age/weight, drug, VeDDRA reaction terms, outcome
limit up to 1000, bounded by the shared ~24 KB page-byte budget (page_omitted reports any cut); skip capped at 25000
Optional stage: true (or canvas_id) stages the matched set for SQL via openfda_dataframe_query
Filter examples: animal.species, drug.brand_name, reaction.veddra_term_name, serious_ae

`openfda_search_drug_shortages` _tool

Filter by status (Current/Resolved), therapeutic_category, generic_name, or company_name
Each record's openfda block carries brand_name, product_ndc, and rxcui for chaining into openfda_get_drug_label or openfda_lookup_ndc
limit up to 1000, bounded by the shared ~24 KB page-byte budget; skip capped at 25000
Optional stage: true (or canvas_id) for DataCanvas SQL via openfda_dataframe_query

`openfda_search_tobacco_reports` _tool

Filter by tobacco_products, reported_health_problems, reported_product_problems, or nonuser_affected
Each report carries number_tobacco_products / number_health_problems / number_product_problems counts alongside the arrays
limit up to 1000, bounded by the shared ~24 KB page-byte budget; skip capped at 25000
Optional stage: true (or canvas_id) for DataCanvas SQL via openfda_dataframe_query

`openfda_search_recalls` _tool

category (drug/food/device) plus endpoint — enforcement covers all categories, recall is device-only and rejects a non-device category as a typed recall_endpoint_non_device error
Filter by classification (Class I/II/III), recalling_firm, reason_for_recall, status
Device recall records carry their own identity and status (product_res_number, recall_status) and no hazard classification; the text output renders each record with its endpoint's fields
limit up to 1000, bounded by the shared ~24 KB page-byte budget — a device record runs several KB against roughly one for drug/food
Optional stage: true (or canvas_id) for DataCanvas SQL via openfda_dataframe_query

`openfda_count_values` _tool

Works across all 20 openFDA endpoints (drug, food, device, animal/veterinary, tobacco, other) — the same set openfda_describe_fields covers
count takes a dotted field path — openfda_describe_fields lists the verified expression for each field (countAs); outside the catalog, append .exact on analyzed text fields and count keyword identifiers (product_ndc, application_number, pma_number) bare
A field that can't be aggregated fails as not_aggregatable, naming the expression that does count or saying the field has none; a search whose matched records lack the field returns an empty tally with a notice
Optional search scopes the aggregation; returns up to 1000 top terms ranked by count descending
truncated is set only when more distinct terms exist past limit (the tool reads one term ahead); at openFDA's 1000-term count maximum no look-ahead is possible, so a full list carries a notice that more may exist instead
Pairs with the search/label/recall tools when sample records help interpret an aggregate
Runs against the live API even when the local bulk mirror is enabled — a partial mirror can't produce complete aggregates

`openfda_describe_fields` _tool

Covers all 20 cataloged openFDA endpoints — the same set openfda_count_values accepts
Returns field paths grouped by category, each with type, a one-line description, and countAs — the live-verified openfda_count_values expression (bare or .exact), or null when the field can't be aggregated — plus queryTips covering quoting, AND/OR, .exact, and date-range syntax
Call before constructing a search query — field paths differ per endpoint and aren't derivable from a tool's own schema

`openfda_get_drug_label` _tool

search targets label fields (openfda.brand_name, openfda.generic_name, openfda.manufacturer_name, or set_id for a specific SPL revision); default limit 5, up to 1000
A page over the ~24 KB inline budget returns kind: "outline" — section names and their serialized size, largest first — instead of label text; re-call with sections: [...] for the ones needed
Outline sizes are summed across the whole page, so cost scales with limit; a sections selection is always returned whole even when it overflows the budget, with its size disclosed
sections narrows each record to the requested keys plus identity metadata (openfda, set_id, id, effective_time, version)
*_table sections render as Markdown tables in the text output (caption, spans, footnotes, and footer rows preserved); structured results keep the raw SPL table markup
skip capped at openFDA's 25000-record pagination ceiling

`openfda_search_drug_approvals` _tool

Filter by brand/generic name (openfda.brand_name), sponsor_name (stored uppercase — a lowercase quoted value matches nothing), or submissions.submission_type / submissions.review_priority
Each record carries the application's full submission history, so limit up to 1000 is bounded by the shared ~24 KB page-byte budget — a long-running application is an order of magnitude larger than a recent one
page_omitted reports any cut with the routes to the rest; skip capped at 25000
Optional stage: true (or canvas_id) for DataCanvas SQL via openfda_dataframe_query

`openfda_search_device_clearances` _tool

pathway selects 510k (174K+ records, most common) or pma (higher-risk devices) — one pathway per call
Filter by applicant, product_code, advisory_committee_description, or openfda.device_name
limit up to 1000, bounded by the shared ~24 KB page-byte budget — a 510(k) record carries a summary narrative and runs several times the size of a PMA record
Optional stage: true (or canvas_id) for DataCanvas SQL via openfda_dataframe_query

`openfda_lookup_ndc` _tool

Search by product_ndc, brand_name, generic_name, openfda.manufacturer_name, or active_ingredients.name
Pair with openfda_get_drug_label via the returned brand_name or set_id to read the package insert
limit up to 1000, bounded by the shared ~24 KB page-byte budget — a product with many packaging configurations is several times the size of one with a single package
Optional stage: true (or canvas_id) for DataCanvas SQL via openfda_dataframe_query; skip capped at 25000

`openfda_dataframe_query` _tool

Runs a single read-only SELECT against a table staged by a search tool's stage: true — DDL, DML, COPY, and file-reading functions are rejected
Scalar fields are stored as text (CAST for numeric math); nested openFDA objects/arrays are JSON columns, queryable with DuckDB JSON functions
Results are capped at the canvas row limit; truncated: true means page the rest with ORDER BY plus LIMIT/OFFSET
Requires CANVAS_PROVIDER_TYPE=duckdb and the optional @duckdb/node-api dependency — errors canvas_disabled otherwise

`openfda_dataframe_describe` _tool

Lists every table on a canvas by canvas_id — name, kind (table/view), full staged row count (not the inline preview count), and column name/DuckDB-type/nullable for each
Nested openFDA objects/arrays are stored as JSON columns — query them with DuckDB JSON functions
Call before openfda_dataframe_query to get exact table and column names
Errors canvas_disabled when CANVAS_PROVIDER_TYPE is unset, canvas_not_found when the canvas_id has expired or never existed

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.

openFDA-specific:

Generic API client for all 20 openFDA endpoints with retry (exponential backoff) and rate-limit awareness
Automatic error normalization — 404 returns empty results, 429/5xx retries, 400 surfaces an actionable message
Optional API key — works without one (1K requests/day), increases to 120K/day with a free key
Optional DataCanvas staging (CANVAS_PROVIDER_TYPE=duckdb, per call with stage: true) — stage large result sets as DuckDB tables, list their columns with openfda_dataframe_describe, and run SQL via openfda_dataframe_query
Optional local bulk mirror (OPENFDA_MIRROR_ENABLED=true) — a self-refreshing SQLite copy of four drug datasets that answers exact-key lookups without spending API budget, with live fallback

Agent-friendly output:

Byte-budget disclosure — oversized pages are bounded by a shared ~24 KB serialized budget and disclosed via page_omitted/page_bytes on both content[] and structuredContent, never silently truncated and never emptied to zero records
Typed failure contracts — errors[] declarations key ctx.fail by reason (rate_limited, query_error, pagination_limit_reached, canvas_disabled, ...) so callers can branch on error.data.reason instead of parsing messages
Best-effort degradation — openfda_drug_profile returns null per section on a miss rather than failing the whole call, and names which sections failed upstream (vs. genuinely absent) in degraded[]
Empty-result guidance — a no-match search returns a notice pointing at openfda_describe_fields and broader query terms rather than a bare empty array; a page requested past the end of its results reports the real match count and says the offset overshot

Getting started

Public Hosted Instance

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

json

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

Self-Hosted / Local

Add the following to your MCP client configuration file:

json

{
  "mcpServers": {
    "openfda-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openfda-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OPENFDA_API_KEY": "your-key-here"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "openfda-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openfda-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OPENFDA_API_KEY": "your-key-here"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "openfda-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openfda-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.3.0 or higher.
Optional: openFDA API key for higher rate limits (120K requests/day vs 1K/day).

Installation

Clone the repository:

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

Navigate into the directory:

cd openfda-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_SESSION_MODE`	HTTP session handling: `stateless`, `stateful`, or `auto`. No tool asks the caller for input mid-call, so no session store is needed.	`stateless`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`OPENFDA_API_KEY`	Free API key from open.fda.gov. Increases daily limit from 1K to 120K requests.	none
`OPENFDA_BASE_URL`	Base URL override for testing against a proxy or mock.	`https://api.fda.gov`
`OPENFDA_MIRROR_ENABLED`	Answer exact-key lookups from a local copy of the openFDA bulk downloads instead of the API. See Local bulk mirror.	`false`
`OPENFDA_MIRROR_PATH`	Directory holding one SQLite file per mirrored dataset.	`./data/openfda-mirror`
`OPENFDA_MIRROR_REFRESH_CRON`	Cron expression for the in-process mirror refresh (HTTP transport only). Unset means no scheduled refresh.	none
`OPENFDA_MIRROR_FALLBACK_LIVE`	Fall back to the live API when the mirror is cold, missing the record, or failing.	`true`
`OPENFDA_MIRROR_REFRESH_TIMEOUT_MS`	Wall-clock budget for one refresh before it is aborted.	`21600000` (6h)
`OPENFDA_MIRROR_BASE_URL`	Host serving the bulk download manifest (`download.json`).	`https://api.fda.gov`
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable DataCanvas staging — analytical SQL over result sets staged with `stage: true` and queried via `openfda_dataframe_query`. Requires the optional `@duckdb/node-api` dependency.	`none` (disabled)
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

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

Local bulk mirror

openFDA publishes whole-dataset JSON dumps alongside the API. With OPENFDA_MIRROR_ENABLED=true the server keeps a local SQLite copy of four of them — drug/label, drug/ndc, drug/enforcement, drug/drugsfda — and answers eligible lookups from it, leaving the API budget for everything else.

The mirror is deliberately narrow. openFDA's search runs server-side in Elasticsearch, which tokenises and ranks; a local corpus cannot reproduce that. A query is answered locally only when all of the following hold, and is sent to the API otherwise:

the search is a single quoted field:"value" term — no boolean operators, wildcards, or ranges;
the field is one of id, set_id, product_id, product_ndc, recall_number, event_id, application_number, and the value is a whole identifier in its canonical spelling and case;
there is no count and no sort, and skip is 0;
the value matches exactly one record.

The last condition is what keeps a mirrored answer identical to the API's rather than merely equivalent. Four of the seven lookup fields are primary keys and always match one record. The other three — set_id, product_ndc, event_id — can address several, and openFDA returns those in relevance order, which a local corpus cannot recompute; such a lookup routes to the API whatever the requested page size.

openfda_count_values therefore always runs against the API — a partial mirror would return plausible but incomplete aggregates.

The initial harvest runs out-of-band, never at startup:

bun run mirror:init                  # all four datasets
bun run mirror:init drug/enforcement # one dataset (~3.8 MB compressed)
bun run mirror:status                # sync state per dataset
bun run mirror:verify                # integrity check + row counts
bun run mirror:refresh               # re-harvest datasets whose dump has advanced

openFDA publishes no incremental API for these endpoints, so a refresh re-reads the whole dump and tombstones records the new export no longer carries. It is idempotent and resumable — re-running after an interrupt continues from the persisted cursor. Set OPENFDA_MIRROR_REFRESH_CRON to run it in-process on the HTTP transport; on stdio, run bun run mirror:refresh from the host.

meta.lastUpdated on a mirrored response reports the last_updated stamp of the dump being served, which can differ from the live API's — the API index and the published dumps advance on separate schedules.

On Node, install the optional better-sqlite3 peer dependency; Bun uses its built-in bun:sqlite. OPENFDA_MIRROR_REFRESH_CRON additionally needs the optional node-cron peer dependency — without it the server refuses to start rather than run with a schedule it cannot honour.

Running the server

Local development

Build and run the production version:

# 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  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

Docker

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

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/openfda-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them. Mount a volume over /usr/src/app/data/openfda-mirror to persist an OPENFDA_MIRROR_ENABLED=true harvest across container replacement.

Project structure

Directory	Purpose
`src/index.ts`	Entry point — `createApp()` with tool registration and service setup.
`src/config/`	Server-specific env var parsing and validation with Zod.
`src/services/openfda/`	openFDA API client with retry, rate-limit handling, and error normalization.
`src/services/openfda/mirror/`	Opt-in local bulk mirror — dataset registry, dump reader, sync ingester, and the query gate that decides mirror vs live.
`src/services/canvas/`	DataCanvas accessor — resolves the active canvas provider for staging and SQL.
`src/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`). Fourteen openFDA tools.
`tests/`	Unit and integration tests mirroring `src/`.

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
Register new tools in src/mcp-server/tools/definitions/index.ts
Validate raw upstream data → normalize to the output schema → never fabricate a field openFDA didn't return

Data attribution

Data is served from openFDA, a U.S. Food and Drug Administration service. Under the openFDA license the data is dedicated to the public domain under CC0 1.0, with one exception: GMDN® device-classification content — Term Code, Term Name, and Term Definition — is licensed from The GMDN Agency, and redistributing it or using it to train AI requires a separate licence from the Agency.

The local mirror therefore covers drug datasets only. device/classification and every other device endpoint are excluded from it, and the ingester rejects any record carrying a GMDN-bearing field rather than writing it to disk. Extending the mirror to device data requires clearing that licence first.

FDA does not endorse this project. Do not rely on openFDA to make decisions regarding medical care.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Tools (14)

openfda_search_adverse_eventsopenfda_search_animal_eventsopenfda_search_drug_shortagesopenfda_search_recallsopenfda_search_tobacco_reportsopenfda_count_valuesopenfda_describe_fieldsopenfda_get_drug_label

Configuration

Environment variables

OPENFDA_API_KEY

Free API key from open.fda.gov — increases daily limit from 1K to 120K requests.

OPENFDA_MIRROR_ENABLEDdefault false

Serve exact-key lookups for drug/label, drug/ndc, drug/enforcement, and drug/drugsfda from a local bulk mirror instead of the API. Off by default; the initial harvest runs out-of-band via the mirror:init script.

OPENFDA_MIRROR_PATHdefault ./data/openfda-mirror

Directory holding one SQLite file per mirrored dataset.

OPENFDA_MIRROR_REFRESH_CRON

Cron expression for the in-process mirror refresh. HTTP transport only; stdio operators run mirror:refresh from the host. Requires the optional node-cron peer dependency.

OPENFDA_MIRROR_FALLBACK_LIVEdefault true

Fall back to the live API when the mirror is cold, missing the record, or failing. Disable to fail loudly instead.

OPENFDA_MIRROR_REFRESH_TIMEOUT_MSdefault 21600000

Wall-clock budget for one scheduled refresh before it is aborted. Raise it for drug/label, the only multi-partition dataset.

OPENFDA_MIRROR_BASE_URLdefault https://api.fda.gov

Host serving the openFDA bulk download manifest. Override only to harvest from a private mirror of the dumps.

MCP_LOG_LEVELdefault info

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

MCP_TRANSPORT_TYPErequireddefault http

Must be set to 'http' for streamable HTTP transport.

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": {
    "openfda-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openfda-mcp-server@0.7.9"
      ],
      "env": {
        "OPENFDA_API_KEY": "<YOUR_OPENFDA_API_KEY>",
        "OPENFDA_MIRROR_ENABLED": "false",
        "OPENFDA_MIRROR_PATH": "./data/openfda-mirror",
        "OPENFDA_MIRROR_REFRESH_CRON": "<YOUR_OPENFDA_MIRROR_REFRESH_CRON>",
        "OPENFDA_MIRROR_FALLBACK_LIVE": "true",
        "OPENFDA_MIRROR_REFRESH_TIMEOUT_MS": "21600000",
        "OPENFDA_MIRROR_BASE_URL": "https://api.fda.gov",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

openfda_search_adverse_events

openfda_search_animal_events

openfda_search_drug_shortages

openfda_search_recalls

openfda_search_tobacco_reports

openfda_count_values

openfda_describe_fields

openfda_get_drug_label

openfda_search_drug_approvals

openfda_search_device_clearances

openfda_lookup_ndc

openfda_drug_profile

openfda_dataframe_describe

openfda_dataframe_query

@cyanheads/openfda-mcp-server

Overview

Tools

Capability reference

openfda_drug_profile tool

openfda_search_adverse_events tool

openfda_search_animal_events tool

openfda_search_drug_shortages tool

openfda_search_tobacco_reports tool

openfda_search_recalls tool

openfda_count_values tool

openfda_describe_fields tool

openfda_get_drug_label tool

openfda_search_drug_approvals tool

openfda_search_device_clearances tool

openfda_lookup_ndc tool

openfda_dataframe_query tool

openfda_dataframe_describe tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Local bulk mirror

Running the server

Local development

Docker

Project structure

Development guide

Data attribution

Contributing

License

Install

Configuration

Related servers

`openfda_drug_profile` _tool

`openfda_search_adverse_events` _tool

`openfda_search_animal_events` _tool

`openfda_search_drug_shortages` _tool

`openfda_search_tobacco_reports` _tool

`openfda_search_recalls` _tool

`openfda_count_values` _tool

`openfda_describe_fields` _tool

`openfda_get_drug_label` _tool

`openfda_search_drug_approvals` _tool

`openfda_search_device_clearances` _tool

`openfda_lookup_ndc` _tool

`openfda_dataframe_query` _tool

`openfda_dataframe_describe` _tool