
openfda-mcp-server
io.github.cyanheads/openfda-mcp-server
Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.
Documentation
@cyanheads/openfda-mcp-server
Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.
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.
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 by 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_describe | List tables and column schemas staged on a DataCanvas |
openfda_dataframe_query | Run read-only SQL over a result set staged on a DataCanvas |
openfda_dataframe_drop | Delete one table staged on a DataCanvas (opt-in, off by default) |
Capability reference
openfda_drug_profile tool
- One
drugname, brand or generic, resolved once to an identity (generic name, NDC, manufacturer, application number, original-packager flag, RxCUI, SPL set ID) from an original packager's label when one matches, else any matching label or the NDC directory, and from the approval application's own label when it has one;meta.resolvedVia(label,ndc,none) names the source, and a single-ingredient product is preferred over combinations approvalis the drug's own Drugs@FDA application, ranked over the name's NDA, BLA, and brand matches; recalls and shortage key onmeta.fanOutKey— the typed name when it is an ingredient of the resolved generic, else that generic- Each section names its product:
shortagegives the product, company, and presentation of the record shown, with the match total and per-status counts, and differingidentity.application_number/approval.applicationNumbermean two products - Recalls also search records openFDA never harmonized (
product_description);recalls_totalgives the match count beside the newest 5 recalls - Sections
label,adverse_events,recalls,approval, andshortageare best-effort and come backnull(or an emptyrecalls) on a miss;degraded[]names each section whose sub-query failed upstream, so a listed section is unknown rather than absent; a sub-query cut by the 50 s profile deadline is listed with reasontimeout - Auth, configuration, and cancellation failures fail the whole call instead of degrading a section
openfda_search_adverse_events tool
category(drug,food,device) selects the endpoint and its record schema;limitdefaults to 5 (cap 25) for drug, 25 (cap 1000) for food, 10 (cap 175) for device- Sortable date fields differ by category:
receivedate(drug),date_created(food),date_received(device); another category's field fails asquery_error; with neithersearchnorsort, results come newest first on that field - Text output lists each reaction with its outcome (
Death — fatal (5)), shows onset age with its unit (3 month (802)), and decodes the coded drug and report fields from FDA's field reference beside the raw value (via oral (048),elderly (6),drug withdrawn (1)); structured output keeps the codes
openfda_search_animal_events tool
- Optional
searchover veterinary reports, e.g.animal.species,drug.active_ingredients.name,reaction.veddra_term_name,serious_ae;limitdefaults to 25, cap 450; a bare browse (nosearch, nosort) is newest first byoriginal_receive_date - Brand and manufacturer names are masked as
MSKon every record, so search by active ingredient;drug.manufacturer.registration_numbernarrows to one approval - Records carry animal species, breed, age, and weight, the drug and route, VeDDRA reaction terms, and outcome
openfda_search_drug_shortages tool
- Optional
searchoverstatus(Current/To Be Discontinued/Resolved),therapeutic_category,generic_name, orcompany_name;limitdefaults to 25, cap 1000 - Each record's
openfdablock carriesbrand_name,product_ndc, andrxcuifor chaining intoopenfda_get_drug_labeloropenfda_lookup_ndc
openfda_search_tobacco_reports tool
- Optional
searchovertobacco_products,reported_health_problems,reported_product_problems, ornonuser_affected;limitdefaults to 25, cap 1000; a bare browse (nosearch, nosort) is newest first bydate_submitted - Reports carry the problem arrays plus
number_tobacco_products,number_health_problems, andnumber_product_problemscounts
openfda_search_recalls tool
category(drug,food,device) plusendpoint:enforcement(default, every category) orrecall(devices only; other categories fail asrecall_endpoint_non_device);limitdefaults to 25 (cap 1000) for drug and food enforcement, 10 (cap 125) for device enforcement, 10 (cap 50) for device recall; a bare browse (nosearch, nosort) is newest first byreport_date(event_date_initiatedfor device recall)- Enforcement records carry
recall_number,classification(Class I/II/III), andstatus; device recall records carryproduct_res_numberandrecall_statusinstead, with no hazard classification
openfda_count_values tool
endpoint(any of the 20 openFDA endpoints), acountfield expression, and an optionalsearch; returns the toplimitterms (default 100, cap 1000; a largerlimitreturns 1000 with a notice), ranked by count; a date field returns one term per distinctYYYYMMDDdate, ranked the same waytruncatedflags more distinct terms pastlimit, 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 asnot_aggregatable(take thecountAsform fromopenfda_describe_fields)- Always runs against the live API, even with the bulk mirror enabled
openfda_describe_fields tool
endpoint: the same 20 endpointsopenfda_count_valuesaccepts- Field paths grouped by category, each with
type, a description, andcountAs(the verified count expression, ornullwhen the field can't be aggregated), plusqueryTipson quoting, AND/OR,.exact, and date ranges
openfda_get_drug_label tool
- Required
searchon label fields (openfda.brand_name,openfda.generic_name,openfda.manufacturer_name,set_id);limitdefaults to 5, cap 1000 (a larger value returns 1000 records with a notice naming the nextskip); an empty search namesspl_product_data_elementsfor labels openFDA never linked to a product - A page over 24,000 bytes returns
kind: "outline"(section names and sizes, largest first) instead of label text; re-call withsections: [...]to get those sections plus identity metadata (openfda,set_id,id,effective_time,version), returned whole even when over budget *_tablesections render as Markdown tables in the text output; structured results keep the raw SPL markup
openfda_search_drug_approvals tool
- Optional
searchoverproducts.brand_name(any letter case;openfda.*covers harmonized applications only),sponsor_name(stored uppercase, so a lowercase quoted value matches nothing),submissions.submission_type, orsubmissions.review_priority; omitted, the page is newest first by latest submission (submissions.submission_status_date:desc), not approval date;limitdefaults to 25, cap 375 - Records carry
application_number,sponsor_name,products[], and the application's fullsubmissions[]history
openfda_search_device_clearances tool
pathway(510korpma, one per call) plus an optionalsearchoverapplicant,product_code,advisory_committee_description, oropenfda.device_name;limitdefaults to 10 (cap 175) for 510(k), 25 (cap 575) for PMA; a bare browse (nosearch, nosort) is newest first bydecision_date- 510(k) records carry
k_number,device_name, anddecision_date; PMA records carrypma_number,trade_name, andsupplement_number
openfda_lookup_ndc tool
- Required
searchoverproduct_ndc,brand_name,generic_name,labeler_name, oractive_ingredients.name;limitdefaults to 25, cap 1000 - Records carry
product_ndc,labeler_name,dosage_form,route,marketing_category,active_ingredients[], andpackaging[]
openfda_dataframe_describe tool
canvas_idfrom a staged search; lists each table'sname,kind, full stagedrow_count, and columns with DuckDB type and nullability- Fails as
canvas_disabledwhenCANVAS_PROVIDER_TYPE=none, orcanvas_not_foundwhen thecanvas_idhas expired or never existed
openfda_dataframe_query tool
canvas_idplus one read-onlySELECT; DDL, DML, COPY, and file-reading functions are rejected. Scalars are stored as text (CASTfor math) and nested openFDA blocks as JSON columns- Rows are capped at the canvas row limit, and
truncated: truemeans page on withORDER BYplusLIMIT/OFFSET; failures arecanvas_disabled,canvas_not_found,missing_table, orinvalid_query
openfda_dataframe_drop tool
- Off by default: set
OPENFDA_DATAFRAME_DROP_ENABLED=trueto make it callable; otherwise it is listed as disabled on the landing page and absent fromtools/list canvas_idplus thetablename fromopenfda_dataframe_describe; deletes that one table or view and returnsremaining_tables, leaving the canvas and its other tables in place- Failures are
canvas_disabled,canvas_not_found, ormissing_table(already dropped, expired, or mistyped)
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:
- One client for all 20 openFDA endpoints, with retry on 429 and 5xx. No API key is needed (1K requests/day); a free
OPENFDA_API_KEYraises that to 120K/day - Queries are
field:valueover dotted paths joined by AND/OR (a URL-style+between clauses reads as a space);openfda_describe_fieldslists the paths, and a malformed query fails asmalformed_searchbefore any request - Paging:
limitis the page size, with a default and cap per endpoint (default 5 and cap 25 for drug adverse events, default 25 and cap 1000 for the shortest records); a larger value is clamped to the cap with a notice, andskipruns up to openFDA's 25,000-record ceiling (pagination_limit_reachedpast it); no page is cut to a byte budget fieldson anyopenfda_search_*tool oropenfda_lookup_ndctrims each record to the dotted paths you name, so large records fit inline- DataCanvas staging (on by default;
CANVAS_PROVIDER_TYPE=noneturns it off) withstage: trueor acanvas_id, and an optional local bulk mirror (OPENFDA_MIRROR_ENABLED=true) that answers exact-key lookups without spending API budget
Agent-friendly output:
- Disclosed bounds: the clamp notice,
projected_fields, the labeloutline, andstaged_rowsreport every clamp, projection, outline, and staging cut;page_bytesandpage_largest_fieldsflag a record over 24,000 bytes - Typed failures: callers branch on
error.data.reason(rate_limited,query_error,not_aggregatable, ...) instead of parsing messages - Unknown vs. absent:
openfda_drug_profilereturnsnullfor a section with no FDA record and lists failed sections indegraded[] - Empty-result guidance: a no-match search points at
openfda_describe_fields, broader terms, and the endpoint's own product-name field
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http openfda-mcp-server https://openfda.caseyjhand.com/mcp
Or run it locally:
claude mcp add openfda-mcp-server -- npx -y @cyanheads/openfda-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"openfda-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/openfda-mcp-server"]
}
}
}
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.
Configuration
| Variable | Description | Default |
|---|---|---|
OPENFDA_API_KEY | Free API key from open.fda.gov; raises the daily limit from 1K to 120K requests. | none |
OPENFDA_BASE_URL | API base URL override, for a proxy or mock. | https://api.fda.gov |
OPENFDA_CLAMP_LIMITS | Clamp a limit above its endpoint's cap to the cap, with a notice; false rejects it and advertises the cap as the schema maximum. | true |
OPENFDA_MIRROR_ENABLED | Answer exact-key lookups from the 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). | 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, in ms. | 21600000 (6h) |
OPENFDA_MIRROR_BASE_URL | Host serving the bulk download manifest (download.json). | https://api.fda.gov |
CANVAS_PROVIDER_TYPE | DataCanvas staging and SQL. none disables them; dataframe tools remain listed and return canvas_disabled. | duckdb |
OPENFDA_DATAFRAME_DROP_ENABLED | Enable openfda_dataframe_drop, which deletes a staged table. Needs CANVAS_PROVIDER_TYPE=duckdb. | false |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | HTTP server port. | 3010 |
MCP_SESSION_MODE | HTTP session mode: stateless, stateful, or auto. | 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). | <app-root>/logs |
STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1. | in-memory |
OTEL_ENABLED | Enable OpenTelemetry. | false |
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.
Local bulk mirror
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:
bun run mirror:init # all four datasets
bun run mirror:init drug/enforcement # one dataset
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
A refresh re-reads the whole dump, and server shutdown stops a refresh in progress; the next refresh resumes it. 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.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
-
Clone and install:
git clone https://github.com/cyanheads/openfda-mcp-server.git cd openfda-mcp-server && bun install cp .env.example .env # optionally set OPENFDA_API_KEY and the mirror or canvas options -
Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http -
Run checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/openfda-mcp-server:latest
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.
Project structure
| Directory | Purpose |
|---|---|
src/index.ts | createApp() entry point: tool registration, service setup, mirror refresh wiring. |
src/config | Server-specific environment variable parsing and validation with Zod. |
src/mcp-server/tools/definitions | Tool definitions (*.tool.ts), fifteen in all. |
src/mcp-server/tools | Shared tool helpers: per-endpoint field catalog, input schemas and guards, formatters, SPL table rendering. |
src/services/openfda | openFDA API client (retry, rate limits, 50 s call deadline, error normalization), oversized-record disclosure, fields record projection, canvas staging. |
src/services/openfda/mirror | Opt-in local bulk mirror: dataset registry, dump reader, harvester, mirror-vs-live query gate, refresh schedule. |
src/services/canvas | DataCanvas accessor for staging and SQL. |
scripts/openfda-mirror.ts | Mirror lifecycle CLI behind the mirror:* scripts. |
tests/ | Unit and integration tests, mirroring the src/ structure. |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor request-scoped logging - Register new tools in the barrel at
src/mcp-server/tools/definitions/index.ts - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate a field openFDA didn't return
Data attribution
Data 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.
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.
@cyanheads/openfda-mcp-servernpm install @cyanheads/openfda-mcp-server@cyanheads/openfda-mcp-servernpm install @cyanheads/openfda-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.