io.github.cyanheads/openfda-mcp-server

Official14 tools

by cyanheads · TypeScript

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

Query FDA drug, food, device, and recall data via openFDA API.

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.

Parameters (6)

categorystringrequired
Product category — each has different field schemas in the response
searchstring
openFDA search query. Examples: patient.drug.medicinalproduct:"aspirin", patient.reaction.reactionmeddrapt:"nausea" AND serious:"1". Omit to browse recent.
sortstring
Sort expression (field:asc or field:desc). Example: receivedate:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000, default 10)
skipnumber
Number of records to skip for pagination (0-25000, default 0)
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

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.

Parameters (5)

searchstring
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.
sortstring
Sort expression (field:asc or field:desc). Example: original_receive_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000, default 10)
skipnumber
Number of records to skip for pagination (0-25000, default 0)
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

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.

Parameters (5)

searchstring
openFDA search query using field:value syntax. Examples: status:"Current", therapeutic_category:"Oncology", generic_name:"carboplatin", company_name:"pfizer". Omit to browse all records. Call openfda_describe_fields({ endpoint: "drug/shortages" }) for the complete field list.
sortstring
Sort expression (field:asc or field:desc). Example: update_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000, default 10)
skipnumber
Number of records to skip for pagination (0-25000, default 0)
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

openfda_search_recalls

Search enforcement reports and recall actions across drugs, food, and devices.

Parameters (7)

categorystringrequired
Product category
endpointstring
Report type. Default enforcement. The recall endpoint is only available for devices.
searchstring
openFDA search query. Examples: classification:"Class I" (also "Class II" or "Class III"), recalling_firm:"pfizer", reason_for_recall:"undeclared allergen".
sortstring
Sort expression (field:asc or field:desc). Example: report_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000).
skipnumber
Pagination offset (0-25000).
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

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.

Parameters (5)

searchstring
openFDA search query using field:value syntax. Examples: tobacco_products:"Electronic cigarette", reported_health_problems:"Seizure", nonuser_affected:"Yes". Omit to browse recent reports.
sortstring
Sort expression (field:asc or field:desc). Example: date_submitted:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000, default 10)
skipnumber
Number of records to skip for pagination (0-25000, default 0)
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

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.

Parameters (4)

endpointstringrequired
Full openFDA endpoint path (e.g. "drug/event", "device/classification")
countstringrequired
Field to count. Append .exact for whole-phrase counting (e.g. "patient.reaction.reactionmeddrapt.exact", "openfda.brand_name.exact")
searchstring
Filter query to scope the count (e.g. patient.drug.medicinalproduct:"metformin")
limitnumber
Number of top terms to return (default 100, max 1000)

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.

Parameters (1)

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

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.

Parameters (4)

searchstringrequired
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.
sortstring
Sort expression (field:asc or field:desc). Example: effective_time:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of results to return (1-1000). Default 5. Labels are large.
skipnumber
Number of results to skip for pagination (0-25000). Default 0.

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.

Parameters (5)

searchstring
openFDA search query. Examples: openfda.brand_name:"humira", sponsor_name:"pfizer", submissions.submission_type:"ORIG" AND submissions.review_priority:"PRIORITY". Omit to browse recent.
sortstring
Sort expression (field:asc or field:desc). Example: submissions.submission_status_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000, default 10)
skipnumber
Number of records to skip for pagination (0-25000, default 0)
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

openfda_search_device_clearances

Search FDA device premarket notifications — 510(k) clearances and PMA approvals.

Parameters (6)

pathwaystringrequired
Premarket pathway. 510(k) is the most common; PMA is for higher-risk devices.
searchstring
openFDA search query. Examples: applicant:"medtronic", advisory_committee_description:"cardiovascular", product_code:"DXN", openfda.device_name:"catheter". Omit to browse recent.
sortstring
Sort expression (field:asc or field:desc). Example: decision_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000).
skipnumber
Pagination offset (0-25000).
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

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.

Parameters (5)

searchstringrequired
openFDA search query. Examples: product_ndc:"0363-0218", brand_name:"aspirin", generic_name:"metformin", openfda.manufacturer_name:"walgreen", active_ingredients.name:"ASPIRIN"
sortstring
Sort expression (field:asc or field:desc). Example: listing_expiration_date:desc. Invalid or non-sortable fields cause a query error — use a documented field name.
limitnumber
Maximum number of records to return (1-1000, default 10)
skipnumber
Number of records to skip for pagination (0-25000, default 0)
canvas_idstring
DataCanvas session id from a prior call. Omit to start a fresh canvas; the response returns a new one when canvas is enabled. When canvas (CANVAS_PROVIDER_TYPE=duckdb) is enabled the full matched set is staged for SQL and limit/skip apply only to the inline path.

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.

Parameters (1)

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

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.

Parameters (1)

canvas_idstringrequired
Canvas ID from an openFDA search tool response.

openfda_dataframe_query

Run a read-only SQL SELECT against a DataCanvas table staged by an openFDA search tool (canvas_id + canvas_table in its response when spilled=true). Enables GROUP BY, COUNT/SUM/AVG, time-series, and joins across the full result set without re-paging the API. Call openfda_dataframe_describe first to get the exact table and column names. 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.

Parameters (2)

canvas_idstringrequired
Canvas ID from an openFDA search tool response (the canvas_id field).
querystringrequired
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".

README.md16 KBView on GitHub

<div align="center"> <h1>@cyanheads/openfda-mcp-server</h1> <p><b>Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.</b> <div>14 Tools</div> </p> </div> <div align="center">

</div> <div align="center">

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

</div>

Tools

Fourteen tools for querying FDA data across drugs, food, devices, animal/veterinary products, and recalls — plus an optional DataCanvas SQL surface for large result sets:

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)

`openfda_drug_profile`

Resolve one drug name to its FDA identity, then return a consolidated profile in a single call — replacing four or five chained lookups.

Resolves a brand or generic name to canonical FDA identifiers once (generic name, NDC, RxCUI, SPL set ID), then keys every sub-query off that identity to avoid the identifier drift that breaks naive tool chaining
Single-ingredient resolution: a single-drug query won't resolve to a combination product
Sections: label highlights, adverse-event summary (top reactions, serious count), recall history, Drugs@FDA approval, and current shortage status
Best-effort — a miss on any section returns null rather than failing the whole call; use the dedicated tool for a deep dive into any area

`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.

Category selection: drug, food, or device — each returns different field schemas
Elasticsearch query syntax for filtering by product, reaction, seriousness, date range
Pagination via limit (up to 1000) and skip (up to 25000)
Formatted output includes report ID, seriousness, patient demographics, reactions, drugs with characterization/indication/route, and all remaining fields

`openfda_count_values`

Aggregate and tally unique values for any field across any openFDA endpoint. Returns ranked term-count pairs sorted by count descending.

Works across all 20 openFDA endpoints (drugs, food, devices, animal/veterinary, tobacco, other)
Use .exact suffix on field names for whole-phrase counting
Optional search filter to scope the aggregation
Returns up to 1000 terms per query

`openfda_search_recalls`

Search enforcement reports and recall actions across drugs, food, and devices.

Supports enforcement (all categories) and recall (devices only) endpoints
Filter by classification (Class I/II/III), recalling firm, reason, status
Formatted output includes recall number, classification, product description, reason, distribution pattern

`openfda_search_device_clearances`

Search FDA device premarket notifications — 510(k) clearances and PMA approvals.

Two pathways: 510k (174K+ records, most common) and pma (higher-risk devices)
Filter by applicant, product code, advisory committee, device name
Formatted output adapts to pathway: 510(k) shows K-number/clearance type, PMA shows supplement info

`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.

Search by brand name, generic name, manufacturer, or set ID
Formatted output dynamically renders all label sections and openfda metadata present in the record
Large sections are automatically truncated to keep output readable
Default limit of 5 — labels are large documents

`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.

Filter by brand name, sponsor, submission type, review priority
Formatted output includes products with active ingredients, dosage forms, routes, and marketing status
Full submission history with type, status, date, and review priority
Pagination via limit (up to 1000) and skip (up to 25000)

`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.

Search by product NDC, brand name, generic name, manufacturer, or active ingredient
Returns product details, active ingredients with strengths, and packaging information
Sortable by listing expiration date or other fields

`openfda_search_animal_events`

Search adverse event reports for veterinary drugs and devices submitted to the FDA Center for Veterinary Medicine (1.3M+ records).

Filter by animal species, breed, drug name, VeDDRA reaction term, or seriousness
Records include animal details (species, gender, age, weight), administered drugs, reactions, and outcomes
Formatted output surfaces key clinical fields; remaining fields rendered via catch-all

`openfda_search_tobacco_reports`

Search problem reports submitted to the FDA for tobacco products, including e-cigarettes, vaping products, cigarettes, and smokeless tobacco.

Filter by product type, reported health problems (e.g. seizure, chest pain), product problems (e.g. battery explosion), or non-user involvement
Formatted output surfaces products, health effects, product defects, and report counts

`openfda_search_drug_shortages`

Search FDA drug shortage records (1,700+ entries, refreshed daily). Returns shortage status, availability notes, therapeutic category, dosage form, manufacturer, and timeline.

Filter by status (Current, Resolved), therapeutic category, generic name, or manufacturer
The openfda block carries brand_name, product_ndc, and rxcui for chaining into openfda_get_drug_label or openfda_lookup_ndc
Pagination via limit (up to 1000) and skip (up to 25000)

`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 discover the correct dotted field paths.

Covers all major endpoints: drug/event, drug/label, drug/shortages, drug/drugsfda, drug/ndc, drug/enforcement, food/event, food/enforcement, device/event, device/510k, device/pma, device/recall, device/enforcement, animalandveterinary/event, tobacco/problem
Returns fields grouped by category (identifiers, dates, clinical fields, etc.) with data type and one-line description
Complements the reactive field hints that appear in notice enrichment when a search returns empty

`openfda_dataframe_query` · `openfda_dataframe_describe`

A DataCanvas SQL surface over staged result sets — opt-in, enabled with CANVAS_PROVIDER_TYPE=duckdb.

With canvas enabled, the multi-row search tools page the full matched set (up to openFDA's 25,000-row ceiling) into a DuckDB table and return an inline preview plus a canvas_id and canvas_table. openfda_dataframe_query runs read-only SELECT (GROUP BY, SUM/COUNT, joins) across the staged rows; openfda_dataframe_describe lists the table and column schemas needed to write valid SQL.
Scalar fields are stored as text (CAST for numeric math); nested openFDA blocks (openfda, patient, products, …) are JSON columns. Pass a canvas_id back into a search tool to accumulate result sets on one canvas for cross-table joins.
Off by default — without CANVAS_PROVIDER_TYPE=duckdb the search tools return inline results exactly as before and the two dataframe tools report that canvas is disabled. Requires the optional @duckdb/node-api dependency; unsupported on Cloudflare Workers.

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

openFDA-specific:

Generic API client for all openFDA endpoints with retry (exponential backoff) and rate-limit awareness
Automatic error normalization — 404 returns empty results, 429/5xx retries, 400 provides actionable messages
Optional API key support — works without a key (1K requests/day), increases to 120K/day with a free key
Optional DataCanvas spillover (CANVAS_PROVIDER_TYPE=duckdb) — stage large result sets as DuckDB tables and run SQL via openfda_dataframe_query

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"
    }
  }
}

Via bunx (no install)

Add to your MCP client config:

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_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`
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable DataCanvas spillover — analytical SQL over staged result sets via `openfda_dataframe_query`. Requires the optional `@duckdb/node-api` dependency; unsupported on Cloudflare Workers.	`none` (disabled)
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

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

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/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`). Fourteen openFDA tools.

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

Contributing

Issues and pull requests 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

Configuration

Environment variables

OPENFDA_API_KEY

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

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'.

claude_desktop_config.json

{
  "mcpServers": {
    "openfda-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openfda-mcp-server@0.4.0"
      ],
      "env": {
        "OPENFDA_API_KEY": "<YOUR_OPENFDA_API_KEY>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

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

Tools

openfda_drug_profile

openfda_search_adverse_events

openfda_count_values

openfda_search_recalls

openfda_search_device_clearances

openfda_get_drug_label

openfda_search_drug_approvals

openfda_lookup_ndc

openfda_search_animal_events

openfda_search_tobacco_reports

openfda_search_drug_shortages

openfda_describe_fields

openfda_dataframe_query · openfda_dataframe_describe

Features

Getting Started

Public Hosted Instance

Via bunx (no install)

Prerequisites

Installation

Configuration

Running the Server

Local Development

Project Structure

Development Guide

Contributing

License

Install

Configuration

`openfda_drug_profile`

`openfda_search_adverse_events`

`openfda_count_values`

`openfda_search_recalls`

`openfda_search_device_clearances`

`openfda_get_drug_label`

`openfda_search_drug_approvals`

`openfda_lookup_ndc`

`openfda_search_animal_events`

`openfda_search_tobacco_reports`

`openfda_search_drug_shortages`

`openfda_describe_fields`

`openfda_dataframe_query` · `openfda_dataframe_describe`