fda-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fda-mcp Search for adverse events related to OZEMPIC"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpThat's it. The server starts on stdio and is ready for any MCP client.
Related MCP server: fda-approvals-mcp
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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Usage with Claude Code
Add directly from the command line:
claude mcp add fda -- uvx fda-mcpTo include an API key for higher rate limits:
claude mcp add fda -e OPENFDA_API_KEY=your-key-here -- uvx fda-mcpOr 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_fdatool with adatasetparameterServer instructions — query syntax and common mistakes are injected into every LLM context automatically
Actionable error messages — inline syntax help, troubleshooting tips, and
.exactsuffix warningsFDA 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 any of the 21 OpenFDA datasets. The |
| Aggregation queries on any endpoint. Returns counts with percentages and narrative summary. Warns when |
| Returns searchable field names for any endpoint. Call before searching if unsure of field names. |
| 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 |
|
Device |
|
Food |
|
Other |
|
Resources (3)
URI | Content |
| OpenFDA query syntax: AND/OR/NOT, wildcards, date ranges, exact matching |
| All 21 endpoints with descriptions |
| 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 |
| (none) | API key for higher rate limits (240 vs 40 req/min) |
|
| HTTP request timeout in seconds |
|
| Max concurrent API requests |
|
| PDF download timeout in seconds |
|
| 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-mcpFrom source
git clone https://github.com/Limecooler/fda-mcp.git
cd fda-mcp
uv sync
uv run fda-mcpOptional: 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-utilsWithout 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-mcpProject 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.pyHow It Works
LLM Usability
The server is designed to be easy for LLMs to use correctly:
Server instructions — Query syntax, workflow guidance, and common mistakes are injected into every LLM context automatically via the MCP protocol (~210 tokens).
Unified tool surface — A single
search_fdatool with a typeddatasetparameter replaces 9 separate search tools, eliminating tool selection confusion.Actionable errors —
InvalidSearchErrorincludes inline syntax quick reference.NotFoundErrorincludes troubleshooting steps and the endpoint used. No more references to invisible MCP resources.Visible warnings — Limit clamping and missing
.exactsuffix produce visible notes instead of silent fallbacks.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.
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_fieldstool provides them on demand.Smart pagination — Default page sizes are low (10 records). Responses include
total_results,showing, andhas_more. When results exceed 100, a tip suggests usingcount_recordsfor 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 |
|
De Novo decision |
|
PMA approval |
|
PMA SSED |
|
PMA supplement |
|
Text extraction uses pdfplumber for machine-generated PDFs, with automatic OCR fallback via pytesseract + pdf2image for scanned documents.
License
MIT
Available Tools
4 toolscount_recordsA
Count/aggregate records by field across any OpenFDA endpoint. Returns top values with counts, percentages, and a narrative summary.
When to use: Getting statistics, distributions, or "top N" lists. For individual records, use search_fda instead.
Args: endpoint: One of the 21 OpenFDA endpoint paths (e.g., "drug/event", "device/510k"). Call list_searchable_fields to see valid endpoints. count_field: Field to aggregate on. IMPORTANT: You MUST add .exact suffix for text fields (e.g., "patient.reaction.reactionmeddrapt.exact"). Without .exact, text fields are tokenized and counts will be wrong. Numeric and date fields do NOT need .exact. search: Optional search filter to narrow records before counting. limit: Number of top values to return (default 10, max 1000).
Examples: Top adverse reactions for a drug: endpoint="drug/event", count_field="patient.reaction.reactionmeddrapt.exact", search='patient.drug.openfda.brand_name:"ASPIRIN"' Device recalls by classification: endpoint="device/enforcement", count_field="classification.exact" Food recall reasons: endpoint="food/enforcement", count_field="reason_for_recall.exact", limit=5
Inputs: endpoint (required), count_field (required), limit, search. Returns: result
get_decision_documentA
Fetch FDA regulatory decision documents (not available via OpenFDA API). Downloads the PDF from FDA servers and extracts text content.
When to use: After finding a device submission via search_fda (e.g., dataset="device_510k" or "device_pma"), use the submission number from those results to retrieve the full decision document.
Args: document_type: Type of document to retrieve. submission_number: FDA identifier. Formats: 510k_summary: "K" + 6 digits (e.g., "K213456") denovo_decision: "DEN" + 6 digits (e.g., "DEN200001") pma_approval/pma_ssed/pma_supplement: "P" + 6 digits (e.g., "P200001") supplement_number: Required for pma_supplement only (e.g., "013"). max_length: Max text characters to return (default 8000). Increase for longer documents.
Examples: document_type="510k_summary", submission_number="K213456" document_type="pma_approval", submission_number="P200001" document_type="pma_supplement", submission_number="P200001", supplement_number="013"
Inputs: document_type (required), submission_number (required), max_length, supplement_number. Returns: result
list_searchable_fieldsA
List searchable fields for any OpenFDA endpoint. Returns field names, types, and descriptions.
When to use: Call this BEFORE searching if you're unsure which field names to use in a search query. Field names vary between endpoints.
Args: endpoint: One of the 21 OpenFDA endpoint paths: Drug: drug/event, drug/label, drug/ndc, drug/drugsfda, drug/enforcement, drug/shortage Device: device/event, device/510k, device/pma, device/classification, device/enforcement, device/recall, device/registrationlisting, device/udi, device/covid19serology Food: food/event, food/enforcement Other: other/historicaldocument, other/substance, other/unii, other/nsde category: "common" for the most frequently used fields (default), "all" for the complete field listing.
Inputs: endpoint (required), category. Returns: result
search_fdaA
Search any of the 21 OpenFDA datasets. Returns individual records.
When to use: Finding specific records — adverse events, drug labels, device submissions, recalls, etc. For aggregation/statistics, use count_records instead. If unsure which fields to search, call list_searchable_fields first.
Args: dataset: Which FDA dataset to search. Options by category:
Drug:
drug_adverse_events — FAERS adverse event reports
drug_labels — SPL drug labeling (package inserts)
drug_ndc — National Drug Code directory
drug_approvals — NDA/ANDA/BLA approval history (Drugs@FDA)
drug_recalls — Drug recall enforcement reports
drug_shortages — Drug shortage reports
Device:
device_adverse_events — MDR adverse event reports
device_510k — 510(k) clearances, De Novo grants, and HDE submissions
device_pma — PMA approvals and supplements
device_classification — Product code classification database
(submission_type_id: 1=510k, 2=PMA, 4=510k Exempt, 6=De Novo, 7=HDE)
device_recalls — Device recall enforcement reports
device_recall_details — Detailed device recall information
device_registration — Facility registrations and product listings
device_udi — Unique Device Identifier database
device_covid19_serology — COVID-19 serology test performance
Food:
food_adverse_events — CAERS adverse event reports
food_recalls — Food/cosmetic recall enforcement reports
Other:
historical_documents — FDA historical documents
substance_data — Substance data (GSRS)
unii — Unique Ingredient Identifier codes
nsde — NDC SPL Data Elements
search: OpenFDA query string. Quote string values and use + for spaces.
limit: Max results to return (default 10, max 100).
skip: Number of results to skip for pagination.
sort: Sort field and direction (e.g., "report_date:desc").Examples: Drug adverse events: dataset="drug_adverse_events", search='patient.drug.openfda.brand_name:"ASPIRIN"' Drug labels: dataset="drug_labels", search='openfda.brand_name:"LIPITOR"' Device 510(k) clearances: dataset="device_510k", search='device_name:"pulse+oximeter"' De Novo grants (also in device_510k): dataset="device_510k", search='decision_code:"DENG"+AND+advisory_committee:"DE"' Food recalls: dataset="food_recalls", search='classification:"Class I"' Device classification lookup: dataset="device_classification", search='device_name:"oximeter"+AND+device_class:2'
Inputs: search (required), dataset (required), skip, sort, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: search_fda returns individual records, count_records provides aggregate statistics, list_searchable_fields shows schema metadata, and get_decision_document fetches FDA decision documents. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern with lowercase underscores: search_fda, count_records, list_searchable_fields, get_decision_document. This makes tool selection predictable and easy.
With 4 tools, the server is well-scoped for the OpenFDA data domain. Each tool earns its place and the count falls comfortably within the ideal 3-15 range.
The tool set covers the full workflow: exploring searchable fields, querying individual records, aggregating counts, and retrieving FDA decision documents. No obvious gaps exist for the stated domain.
Maintenance
Related MCP Connectors
FDA 510(k)s, PMAs, recalls & trials, linked: predicate search and review-time stats for AI agents.
FDA medical-device regulatory intelligence from keyless openFDA datasets.
FDA 510(k)/PMA/De Novo, GUDID, recall and EUDAMED device and certificate data. Read-only, no login.
Government contracts, business registration, FDA recalls and product-price data as agent tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to query and analyze FDA adverse events, drug labels, medical device clearances, and other public health datasets through natural language commands.14-
- AlicenseNot gradedqualityDmaintenanceEnables querying FDA drug approvals, device clearances (510(k)), recalls, and adverse events via the openFDA API, providing tools for clinical and pharmaceutical research.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to access FDA and ClinicalTrials.gov data for medical device compliance, adverse event monitoring, and regulatory due diligence.-
- AlicenseAqualityDmaintenanceEnables LLMs to search FDA drug labels and adverse event data via the OpenFDA API, supporting natural language queries for drug safety information.2MIT