convez.ai
MCP ServerDados & AnalyticsIntermediário
cyanheads

OpenFDA MCP Server

cyanheads/openfda-mcp-server

Acesso estruturado aos dados FDA via 14 tools especializadas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece acesso programático aos dados públicos da FDA sobre medicamentos, alimentos, dispositivos médicos e recalls. Expõe 14 ferramentas para consulta, agregação e análise de dados regulatórios americanos, com suporte a STDIO e HTTP streaming.

Instalação

$npx convez-ai cyanheads/openfda-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
3
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.10.0
Issues abertas
6
Contribuidores
1

Casos de uso

  • Pesquisa de eventos adversos e farmacovigilância de medicamentos
  • Monitoramento de recalls de produtos alimentícios e dispositivos
  • Consulta de status de aprovação e disponibilidade de medicamentos
  • Análise regulatória e conformidade em saúde

Veredito

Ferramenta robusta e bem-estruturada para acesso aos dados FDA públicos. Adequada para aplicações de saúde, pesquisa e compliance que precisam de dados regulatórios americanos confiáveis. Requer API key e conhecimento mínimo da estrutura de dados FDA.

README

A tradução para o português deste README ainda está na fila.

npm Version MCP SDK License TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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


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:

ToolDescription
openfda_drug_profileOne drug name → consolidated FDA profile: identity, label, adverse events, recalls, approval, shortage
openfda_search_adverse_eventsSearch adverse event reports across drugs, food, and devices
openfda_search_animal_eventsSearch adverse event reports for veterinary drugs and devices
openfda_search_drug_shortagesSearch FDA drug shortage records — status, availability, therapeutic category, manufacturer
openfda_search_tobacco_reportsSearch problem reports for tobacco products, e-cigarettes, and vaping devices
openfda_search_recallsSearch enforcement reports and recall actions across drugs, food, and devices
openfda_count_valuesAggregate and tally unique values for any field across any openFDA endpoint
openfda_describe_fieldsReturn searchable field paths for an openFDA endpoint, grouped by category
openfda_get_drug_labelLook up FDA drug labeling (package inserts / SPL documents)
openfda_search_drug_approvalsSearch the Drugs@FDA database for NDA/ANDA application approvals
openfda_search_device_clearancesSearch FDA device premarket notifications — 510(k) clearances and PMA approvals
openfda_lookup_ndcLook up drugs in the NDC (National Drug Code) Directory
openfda_dataframe_queryRun read-only SQL over a result set staged on a DataCanvas (opt-in)
openfda_dataframe_describeList 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:

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

Via bunx (no install)

Add to your MCP client config:

{
  "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):

{
  "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:

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

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/openfda-mcp-server.git
  1. Navigate into the directory:
cd openfda-mcp-server
  1. Install dependencies:
bun install

Configuration

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

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or httpstdio
MCP_HTTP_PORTHTTP server port3010
MCP_AUTH_MODEAuthentication: none, jwt, or oauthnone
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.)info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1in-memory
OPENFDA_API_KEYFree API key from open.fda.gov. Increases daily limit from 1K to 120K requests.none
OPENFDA_BASE_URLBase URL override for testing against a proxy or mock.https://api.fda.gov
CANVAS_PROVIDER_TYPESet 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_ENABLEDEnable OpenTelemetryfalse

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

DirectoryPurpose
src/index.tsEntry 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.

Ver o original no GitHub

Bom para

Relacionados