io.github.cyanheadsPublished by GitHub account cyanheadsv0.9.1Updated Oct 29, 2026
Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.
Queries the openFDA public API so an assistant can search FDA drug, food, device, tobacco and veterinary records, look up labels and NDC codes, and run SQL…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Fopenfda-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"openfda": {
"type": "http",
"url": "https://openfda.caseyjhand.com/mcp"
}
}
}Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.
Public Hosted Server: https://openfda.caseyjhand.com/mcp
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.
openfda_drug_profile tooldrug name, brand or generic, resolved once to an identity (generic name, NDC, RxCUI, SPL set ID); recalls, approval, and shortage key on meta.fanOutKey — the typed name when it is an ingredient of the resolved generic, else that generic; meta.resolvedVia (label, ndc, none) names the source, and a single-ingredient product is preferred over combinationsproduct_description, products.active_ingredients.name); recalls_total gives the match count beside the newest 5 recallslabel, adverse_events, recalls, approval, and shortage are best-effort and come back null (or an empty recalls) on a miss; degraded[] names each section whose sub-query failed upstream, so a listed section is unknown rather than absentopenfda_search_adverse_events toolcategory (drug, food, device) selects the endpoint and its record schema; up to 1000 records per pagereceivedate (drug), date_created (food), date_received (device); another category's field fails as query_errorvia oral (048), fatal (5), elderly (6)); structured output keeps the codesopenfda_search_animal_events toolsearch over veterinary reports, e.g. animal.species, drug.active_ingredients.name, reaction.veddra_term_name, serious_ae; up to 1000 records per pageMSK on every record, so search by active ingredient; drug.manufacturer.registration_number narrows to one approvalopenfda_search_drug_shortages toolsearch over status (Current / To Be Discontinued / Resolved), therapeutic_category, generic_name, or company_name; up to 1000 records per pageopenfda block carries brand_name, product_ndc, and rxcui for chaining into openfda_get_drug_label or openfda_lookup_ndcopenfda_search_tobacco_reports toolsearch over tobacco_products, reported_health_problems, reported_product_problems, or nonuser_affected; up to 1000 records per pagenumber_tobacco_products, number_health_problems, and number_product_problems countsopenfda_search_recalls toolcategory (drug, food, device) plus endpoint: enforcement (default, every category) or recall (devices only; other categories fail as recall_endpoint_non_device); up to 1000 records per pagerecall_number, classification (Class I/II/III), and status; device recall records carry product_res_number and recall_status instead, with no hazard classificationopenfda_count_values toolendpoint (any of the 20 openFDA endpoints), a count field expression, and an optional search; returns up to 1000 top terms (default 100), ranked by count; a date field returns one term per distinct YYYYMMDD date, ranked the same waytruncated flags more distinct terms past limit, except at the 1000-term maximum, where a notice says completeness can't be known (a date count is exact at any limit, since openFDA sends every date); an expression openFDA can't aggregate fails as not_aggregatable (take the countAs form from openfda_describe_fields)openfda_describe_fields toolendpoint: the same 20 endpoints openfda_count_values acceptstype, a description, and countAs (the verified count expression, or null when the field can't be aggregated), plus queryTips on quoting, AND/OR, .exact, and date rangesopenfda_get_drug_label toolsearch on label fields (openfda.brand_name, openfda.generic_name, openfda.manufacturer_name, set_id); limit defaults to 5, max 1000kind: "outline" (section names and sizes, largest first) instead of label text; re-call with sections: [...] to get those sections plus identity metadata (openfda, set_id, id, effective_time, version), returned whole even when over budget*_table sections render as Markdown tables in the text output; structured results keep the raw SPL markupopenfda_search_drug_approvals toolsearch over openfda.brand_name, sponsor_name (stored uppercase, so a lowercase quoted value matches nothing), submissions.submission_type, or submissions.review_priority; up to 1000 records per pageapplication_number, sponsor_name, products[], and the application's full submissions[] historyopenfda_search_device_clearances toolpathway (510k or pma, one per call) plus an optional search over applicant, product_code, advisory_committee_description, or openfda.device_name; up to 1000 records per pagek_number, device_name, and decision_date; PMA records carry pma_number, trade_name, and supplement_numberopenfda_lookup_ndc toolsearch over product_ndc, brand_name, generic_name, openfda.manufacturer_name, or active_ingredients.name; up to 1000 records per pageproduct_ndc, labeler_name, dosage_form, route, marketing_category, active_ingredients[], and packaging[]openfda_dataframe_describe toolcanvas_id from a staged search; lists each table's name, kind, full staged row_count, and columns with DuckDB type and nullabilitycanvas_disabled when CANVAS_PROVIDER_TYPE=none, or canvas_not_found when the canvas_id has expired or never existedopenfda_dataframe_query toolcanvas_id plus one read-only SELECT; DDL, DML, COPY, and file-reading functions are rejected. Scalars are stored as text (CAST for math) and nested openFDA blocks as JSON columnstruncated: true means page on with ORDER BY plus LIMIT/OFFSET; failures are canvas_disabled, canvas_not_found, missing_table, or invalid_queryopenfda_dataframe_drop toolOPENFDA_DATAFRAME_DROP_ENABLED=true to make it callable; otherwise it is listed as disabled on the landing page and absent from tools/listcanvas_id plus the table name from openfda_dataframe_describe; deletes that one table or view and returns remaining_tables, leaving the canvas and its other tables in placecanvas_disabled, canvas_not_found, or missing_table (already dropped, expired, or mistyped)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:
OPENFDA_API_KEY raises that to 120K/dayfield:value over dotted paths joined by AND/OR (a URL-style + between clauses reads as a space); openfda_describe_fields lists the paths, and a malformed query fails as malformed_search before any requestlimit up to 1000 and skip up to openFDA's 25,000-record ceiling (pagination_limit_reached past it); each page is held to a 24,000-byte budgetfields on any openfda_search_* tool or openfda_lookup_ndc trims each record to the dotted paths you name, so large records fit inlineCANVAS_PROVIDER_TYPE=none turns it off) with stage: true or a canvas_id, and an optional local bulk mirror (OPENFDA_MIRROR_ENABLED=true) that answers exact-key lookups without spending API budgetAgent-friendly output:
page_omitted, page_bytes, page_largest_fields, projected_fields, the label outline, and staged_rows report every cuterror.data.reason (rate_limited, query_error, not_aggregatable, ...) instead of parsing messagesopenfda_drug_profile returns null for a section with no FDA record and lists failed sections in degraded[]openfda_describe_fields and broader termsConnect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
No API key is needed. A free openFDA API key set as OPENFDA_API_KEY raises the limit from 1K to 120K requests per day. For Docker or a source build, see Running the server.
See .env.example for the full list of optional overrides.
The Claude Desktop MCPB bundle disables DataCanvas because it excludes platform-specific DuckDB bindings. Use npm or Docker for staging and SQL.
With OPENFDA_MIRROR_ENABLED=true the server keeps a local SQLite copy of four openFDA bulk dumps (drug/label, drug/ndc, drug/enforcement, drug/drugsfda). Only exact lookups are answered locally: a single quoted field:"value" term on id, set_id, product_id, product_ndc, recall_number, event_id, or application_number, with no count or sort, skip 0, and one matching record. Everything else goes to the API.
The initial harvest runs separately, never at startup:
A refresh re-reads the whole dump. Set OPENFDA_MIRROR_REFRESH_CRON to run it in-process on the HTTP transport; on stdio, run bun run mirror:refresh from the host. A mirrored response's meta.lastUpdated is the served dump's stamp, which can differ from the live API's.
On Node, install the optional better-sqlite3 peer dependency (Bun uses its built-in bun:sqlite). OPENFDA_MIRROR_REFRESH_CRON also needs the optional node-cron peer dependency; without it the server fails at startup.
Requires Bun v1.4.0 or higher (or Node.js v24+).
Clone and install:
Build and run:
Run checks and tests:
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/openfda-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openfda-mcp-server:latest"]. To build locally, docker build -t openfda-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them. To keep a mirror harvest across container replacement, mount a volume over /usr/src/app/data/openfda-mirror.
See CLAUDE.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for request-scoped loggingsrc/mcp-server/tools/definitions/index.tsData comes 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.
That is why the local mirror 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.
FDA does not endorse this project. Do not rely on openFDA to make decisions regarding medical care.
Issues are welcome. Run checks and tests before submitting:
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Source: README.md at commit 9109a54
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.
skipsortlimitstagefieldssearchcategoryrequiredcanvas_idOpenfda 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. Brand and manufacturer names are masked as "MSK" on every record (the FDA null flavor for withheld data), so find a product by active ingredient on drug.active_ingredients.name, unsuffixed. An ingredient search spans every product containing it and cannot attribute reports to one brand; drug.manufacturer.registration_number (the full value, e.g. "USA-USFDACVM-N141426") narrows it to one approval. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.
skipsortlimitstagefieldssearchcanvas_idOpenfda 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.
skipsortlimitstagefieldssearchcanvas_idOpenfda 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.
skipsortlimitstagefieldssearchcategoryrequiredendpointcanvas_idOpenfda 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.
skipsortlimitstagefieldssearchcanvas_idOpenfda Count Values
Aggregate and tally unique values for any field across any openFDA endpoint. Returns ranked term-count pairs sorted by count descending; a date field tallies one term per distinct YYYYMMDD date, ranked the same way. 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.
countrequiredlimitsearchendpointrequiredOpenfda 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.
endpointrequiredOpenfda 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.
skipsortlimitsearchrequiredsectionsOpenfda 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.
skipsortlimitstagefieldssearchcanvas_idOpenfda 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.
skipsortlimitstagefieldssearchpathwayrequiredcanvas_idOpenfda 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.
skipsortlimitstagefieldssearchrequiredcanvas_idOpenfda 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.
drugrequiredOpenfda 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.
canvas_idrequiredOpenfda 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.
queryrequiredcanvas_idrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
claude mcp add --transport http openfda-mcp-server https://openfda.caseyjhand.com/mcpclaude mcp add openfda-mcp-server -- npx -y @cyanheads/openfda-mcp-server{ "mcpServers": { "openfda-mcp-server": { "command": "npx", "args": ["-y", "@cyanheads/openfda-mcp-server"] } }}bun run mirror:init # all four datasetsbun run mirror:init drug/enforcement # one datasetbun run mirror:status # sync state per datasetbun run mirror:verify # integrity check + row countsbun run mirror:refresh # re-harvest datasets whose dump has advancedgit clone https://github.com/cyanheads/openfda-mcp-server.gitcd openfda-mcp-server && bun installcp .env.example .env # optionally set OPENFDA_API_KEY and the mirror or canvas options# One-time buildbun run rebuild
# Run the built serverbun run start:stdio# orbun run start:httpbun run devcheck # Lint, format, typecheck, securitybun run test # Vitest test suitebun run lint:mcp # Validate MCP definitions against specdocker run --rm -p 3010:3010 ghcr.io/cyanheads/openfda-mcp-server:latestbun run devcheckbun run test