fda-mcp

FDA MCP Server

  

An MCP server that provides LLM-optimized access to FDA data through the OpenFDA API and direct FDA document retrieval. Covers all 21 OpenFDA endpoints plus regulatory decision documents (510(k) summaries, De Novo decisions, PMA approval letters).

Quick Start

No clone or local build required. Install uv and run directly from PyPI:

uvx fda-mcp

That's it. The server starts on stdio and is ready for any MCP client.

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fda": {
      "command": "uvx",
      "args": ["fda-mcp"],
      "env": {
        "OPENFDA_API_KEY": "your-key-here"
      }
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Usage with Claude Code

Add directly from the command line:

claude mcp add fda -- uvx fda-mcp

To include an API key for higher rate limits:

claude mcp add fda -e OPENFDA_API_KEY=your-key-here -- uvx fda-mcp

Or add interactively within Claude Code using the /mcp slash command.

API Key (Optional)

The OPENFDA_API_KEY environment variable is optional. Without it you get 40 requests/minute. With a free key from open.fda.gov you get 240 requests/minute.

Features

• 4 MCP tools — one unified search tool, count/aggregation, field discovery, and document retrieval
• 3 MCP resources for query syntax help, endpoint reference, and field discovery
• All 21 OpenFDA endpoints accessible via a single search_fda tool with a dataset parameter
• Server instructions — query syntax and common mistakes are injected into every LLM context automatically
• Actionable error messages — inline syntax help, troubleshooting tips, and .exact suffix warnings
• FDA decision documents — downloads and extracts text from 510(k) summaries, De Novo decisions, PMA approvals, SSEDs, and supplements
• OCR fallback for scanned PDF documents (older FDA submissions)
• Context-efficient responses — summarized output, field discovery on demand, pagination guidance

Tools

| Tool | Purpose | |------|---------| | search_fda | Search any of the 21 OpenFDA datasets. The dataset parameter selects the endpoint (e.g., drug_adverse_events, device_510k, food_recalls). Accepts search, limit, skip, and sort. | | count_records | Aggregation queries on any endpoint. Returns counts with percentages and narrative summary. Warns when .exact suffix is missing on text fields. | | list_searchable_fields | Returns searchable field names for any endpoint. Call before searching if unsure of field names. | | get_decision_document | Fetches FDA regulatory decision PDFs and extracts text. Supports 510(k), De Novo, PMA, SSED, and supplement documents. |

Dataset Values for search_fda

| Category | Datasets | |----------|----------| | Drug | drug_adverse_events, drug_labels, drug_ndc, drug_approvals, drug_recalls, drug_shortages | | Device | device_adverse_events, device_510k, device_pma, device_classification, device_recalls, device_recall_details, device_registration, device_udi, device_covid19_serology | | Food | food_adverse_events, food_recalls | | Other | historical_documents, substance_data, unii, nsde |

Resources (3)

| URI | Content | |-----|---------| | fda://reference/query-syntax | OpenFDA query syntax: AND/OR/NOT, wildcards, date ranges, exact matching | | fda://reference/endpoints | All 21 endpoints with descriptions | | fda://reference/fields/{endpoint} | Per-endpoint field reference |

Example Queries

Once connected, you can ask Claude things like:

• "Search for adverse events related to OZEMPIC"
• "Find all Class I device recalls from 2024"
• "What are the most common adverse reactions reported for LIPITOR?"
• "Get the 510(k) summary for K213456"
• "Search for PMA approvals for cardiovascular devices"
• "How many drug recalls has Pfizer had? Break down by classification."
• "Find the drug label for metformin and summarize the warnings"
• "What COVID-19 serology tests has Abbott submitted?"

Configuration

All configuration is via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | OPENFDA_API_KEY | (none) | API key for higher rate limits (240 vs 40 req/min) | | OPENFDA_TIMEOUT | 30 | HTTP request timeout in seconds | | OPENFDA_MAX_CONCURRENT | 4 | Max concurrent API requests | | FDA_PDF_TIMEOUT | 60 | PDF download timeout in seconds | | FDA_PDF_MAX_LENGTH | 8000 | Default max text characters extracted from PDFs |

OpenFDA Query Syntax

The search parameter on all tools uses OpenFDA query syntax:

# AND
patient.drug.openfda.brand_name:"ASPIRIN"+AND+serious:1

# OR (space = OR)
brand_name:"ASPIRIN" brand_name:"IBUPROFEN"

# NOT
NOT+classification:"Class III"

# Date ranges
decision_date:[20230101+TO+20231231]

# Wildcards (trailing only, min 2 chars)
device_name:pulse*

# Exact matching (required for count queries)
patient.reaction.reactionmeddrapt.exact:"Nausea"

Use list_searchable_fields or the fda://reference/query-syntax resource for the full reference.

Installation Options

From PyPI (recommended)

# Run directly without installing
uvx fda-mcp

# Or install as a persistent tool
uv tool install fda-mcp

# Or install with pip
pip install fda-mcp

From source

git clone https://github.com/Limecooler/fda-mcp.git
cd fda-mcp
uv sync
uv run fda-mcp

Optional: OCR support for scanned PDFs

Many older FDA documents (pre-2010) are scanned images. To extract text from these:

# macOS
brew install tesseract poppler

# Linux (Debian/Ubuntu)
apt install tesseract-ocr poppler-utils

Without these, the server still works — it returns a helpful message when it encounters a scanned document it can't read.

Development

# Install with dev dependencies
git clone https://github.com/Limecooler/fda-mcp.git
cd fda-mcp
uv sync --all-extras

# Run unit tests (187 tests, no network)
uv run pytest

# Run integration tests (hits real FDA API)
OPENFDA_TIMEOUT=60 uv run pytest -m integration

# Run a specific test file
uv run pytest tests/test_endpoints.py -v

# Start the server directly
uv run fda-mcp

Project Structure

src/fda_mcp/
├── server.py              # FastMCP server entry point
├── config.py              # Environment-based configuration
├── errors.py              # Custom error types
├── openfda/
│   ├── endpoints.py       # Enum of all 21 endpoints
│   ├── client.py          # Async HTTP client with rate limiting
│   └── summarizer.py      # Response summarization per endpoint
├── documents/
│   ├── urls.py            # FDA document URL construction
│   └── fetcher.py         # PDF download + text extraction + OCR
├── tools/
│   ├── _helpers.py        # Shared helpers (limit clamping)
│   ├── search.py          # search_fda tool (all 21 endpoints)
│   ├── count.py           # count_records tool
│   ├── fields.py          # list_searchable_fields tool
│   └── decision_documents.py
└── resources/
    ├── query_syntax.py    # Query syntax reference
    ├── endpoints_resource.py
    └── field_definitions.py

How It Works

LLM Usability

The server is designed to be easy for LLMs to use correctly:

1. Server instructions — Query syntax, workflow guidance, and common mistakes are injected into every LLM context automatically via the MCP protocol (~210 tokens).

1. Unified tool surface — A single search_fda tool with a typed dataset parameter replaces 9 separate search tools, eliminating tool selection confusion.

1. Actionable errors — InvalidSearchError includes inline syntax quick reference. NotFoundError includes troubleshooting steps and the endpoint used. No more references to invisible MCP resources.

1. Visible warnings — Limit clamping and missing .exact suffix produce visible notes instead of silent fallbacks.

1. Response summarization — Each endpoint type has a custom summarizer that extracts key fields and flattens nested structures. Drug labels truncate sections to 2,000 chars. PDF text defaults to 8,000 chars.

1. Field discovery via tool — Instead of listing all searchable fields in tool descriptions (which would cost ~8,000-11,000 tokens of persistent context), the list_searchable_fields tool provides them on demand.

1. Smart pagination — Default page sizes are low (10 records). Responses include total_results, showing, and has_more. When results exceed 100, a tip suggests using count_records for aggregation.

FDA Decision Documents

These documents are not available through the OpenFDA API. The server constructs URLs and fetches directly from accessdata.fda.gov:

| Document Type | URL Pattern | |--------------|-------------| | 510(k) summary | https://www.accessdata.fda.gov/cdrh_docs/reviews/{K_NUMBER}.pdf | | De Novo decision | https://www.accessdata.fda.gov/cdrh_docs/reviews/{DEN_NUMBER}.pdf | | PMA approval | https://www.accessdata.fda.gov/cdrh_docs/pdf{YY}/{P_NUMBER}A.pdf | | PMA SSED | https://www.accessdata.fda.gov/cdrh_docs/pdf{YY}/{P_NUMBER}B.pdf | | PMA supplement | https://www.accessdata.fda.gov/cdrh_docs/pdf{YY}/{P_NUMBER}S{###}A.pdf |

Text extraction uses pdfplumber for machine-generated PDFs, with automatic OCR fallback via pytesseract + pdf2image for scanned documents.

License

MIT