# OpenFDA MCP Server

[![CI](https://github.com/colbyw5/openfda-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/colbyw5/openfda-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)

A Python [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI assistants access to the U.S. Food and Drug Administration's public datasets through the [openFDA API](https://open.fda.gov/). Query drug adverse events, product labeling, recalls, approvals, shortages, NDC directory data, and medical device regulatory information — all from your AI assistant.

> **Demo placeholder:** a GIF or screenshot of the server answering a real query in Claude Desktop / the MCP Inspector belongs here. Not generated yet — this environment has no way to drive Claude Desktop or capture a screen. Add one under `docs/assets/` and swap this callout for `![demo](docs/assets/demo.gif)` when available.

## Features

- **10 search tools** covering drugs and medical devices
- **Async HTTP client** built on httpx for fast, concurrent requests
- **Pagination and counting** — skip/limit and field-level frequency counts out of the box
- **Optional API key** — works without one (1k req/hr); set `FDA_API_KEY` for 120k req/hr
- **Clean JSON responses** with metadata summaries for the LLM

## Tools

### Drug tools

| Tool | Description |
|------|-------------|
| `search_drug_adverse_events` | Search FDA Adverse Event Reporting System (FAERS) data |
| `search_drug_labels` | Search drug product labeling (SPL) information |
| `search_drug_ndc` | Query the National Drug Code (NDC) directory |
| `search_drug_recalls` | Find drug recall enforcement reports |
| `search_drug_approvals` | Search the Drugs@FDA database for approved products |
| `search_drug_shortages` | Query current drug shortage reports |

### Device tools

| Tool | Description |
|------|-------------|
| `search_device_510k` | Search FDA 510(k) premarket clearance data |
| `search_device_classifications` | Search FDA medical device classifications |
| `search_device_adverse_events` | Search medical device adverse event (MDR) reports |
| `search_device_recalls` | Search medical device recall enforcement reports |

## Installation

### Prerequisites

- [pixi](https://prefix.dev/docs/pixi/) (recommended) or Python 3.11+

### With pixi

```bash
git clone https://github.com/colbyw5/openfda-mcp-server.git
cd openfda-mcp-server
pixi install
```

### With pip

```bash
pip install -e .
```

## Configuration

All tools work without an API key, but you'll be limited to 1,000 requests per hour. For higher limits:

1. Get a free API key at [open.fda.gov/apis/authentication](https://open.fda.gov/apis/authentication/)
2. Copy the example env file and add your key:

```bash
cp .env.example .env
# edit .env and paste your key
```

The server loads `.env` automatically on startup via `python-dotenv`. Alternatively, set the environment variable directly:

```bash
export FDA_API_KEY="your-key-here"
```

## Usage

### Running the server

```bash
pixi run serve
# or
openfda-mcp-server
```

The server communicates over stdio, designed for use with MCP-compatible AI assistants.

### MCP client configuration

#### Claude Code

```json
{
  "mcpServers": {
    "openfda": {
      "command": "pixi",
      "args": ["run", "serve"],
      "cwd": "/path/to/openfda-mcp-server",
      "env": {
        "FDA_API_KEY": "your-key"
      }
    }
  }
}
```

#### Claude Desktop

Claude Desktop launches MCP servers as a GUI process, which doesn't inherit your shell's `PATH` or working directory. Use an absolute path to the `pixi` binary and `--manifest-path` instead of `cwd`:

```json
{
  "mcpServers": {
    "openfda": {
      "command": "/opt/homebrew/bin/pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/openfda-mcp-server/pixi.toml",
        "serve"
      ],
      "env": {
        "FDA_API_KEY": "your-key"
      }
    }
  }
}
```

Find your `pixi` binary path with `which pixi` if it's not at `/opt/homebrew/bin/pixi` (e.g. `/usr/local/bin/pixi` on Intel Macs, or `~/.pixi/bin/pixi`).

### Example queries

Once connected, your AI assistant can answer questions like:

- "What adverse events have been reported for Ozempic?"
- "Show me Class I drug recalls from the past year"
- "Look up the NDC codes for metformin"
- "What 510(k) clearances has Medtronic received for cardiac devices?"
- "Are there any current drug shortages for antibiotics?"

### openFDA search syntax

All tools accept a `search` parameter using [openFDA query syntax](https://open.fda.gov/apis/query-syntax/):

```
# Exact match
patient.drug.openfda.brand_name:"aspirin"

# Date range
receivedate:[20240101+TO+20241231]

# AND / OR
openfda.brand_name:"lipitor"+AND+serious:1

# Count a field (returns frequency data instead of records)
count=patient.reaction.reactionmeddrapt.exact
```

## How it works

Your MCP client (Claude Desktop, Claude Code, etc.) talks to this server over stdio using the MCP protocol. The [FastMCP](https://github.com/modelcontextprotocol/python-sdk) server (`server.py`) dispatches each tool call to a handler in `tools.py`, which uses an async httpx client (`client.py`) to query the openFDA REST API and formats the JSON response for the LLM.

```
MCP client ⇄ (stdio) ⇄ FastMCP server ⇄ async httpx client ⇄ openFDA REST API
```

## Data caveats & limitations

FAERS and other openFDA datasets are **spontaneous reports, not incidence rates**. There is no denominator (total exposed population), so you cannot compute risk or incidence from report counts alone — only relative frequency within the dataset. Keep in mind:

- **Report volume reflects reporting behavior, not risk.** Counts are inflated by prescription volume, time on market, and media/litigation attention, independent of any actual safety signal.
- **A single report can list multiple reactions.** Reaction counts don't sum to the number of reports, and one severe report can contribute many reaction terms.
- **Duplicate reports exist** in FAERS (the same case reported by both a patient and a provider, for example) and are not fully deduplicated by the API.
- **Raw frequency is not signal detection.** Real pharmacovigilance signal detection uses disproportionality measures — Proportional Reporting Ratio (PRR) or Reporting Odds Ratio (ROR) — comparing a drug/event pair against a comparator, not raw counts. See [`examples/prr_example.py`](examples/prr_example.py) for a worked calculation.

The data is [CC0 public domain](https://open.fda.gov/license/) — no attribution is legally required — but every tool response includes openFDA's disclaimer, which is worth reading: **do not rely on this data to make medical care decisions**; assume all results are unvalidated. See openFDA's [terms of service](https://open.fda.gov/terms/) for full details.

## Examples

`examples/prr_example.py` computes a Proportional Reporting Ratio (PRR) for an adverse reaction between two drugs, using live FAERS report counts:

```bash
pixi run python examples/prr_example.py --drug ozempic --comparator victoza --reaction nausea
```

It prints the underlying report counts, the PRR, a plain-language interpretation, and the caveats that apply to it (see [Data caveats & limitations](#data-caveats--limitations) above — this is an unadjusted, single-comparator calculation, not a validated signal-detection result).

## Development

```bash
pixi run test       # run tests
pixi run lint       # lint with ruff
pixi run fmt        # format with ruff
pixi run typecheck  # type check with pyright
```

## Project structure

```
openfda-mcp-server/
├── pixi.toml                          # environment and task config
├── pyproject.toml                     # package metadata
└── src/openfda_mcp_server/
    ├── client.py                      # async httpx client for openFDA API
    ├── server.py                      # FastMCP server entry point
    └── tools.py                       # MCP tool definitions and handlers
```

## License

[MIT](LICENSE)