Food Safety & Recall MCP

A production-ready Model Context Protocol (MCP) server that exposes FDA food safety data — recalls, adverse events, and safety alerts — powered by OpenFDA.

Built with FastMCP and Python. Deployable to Apify or any Docker-compatible host.

---

Tools

food_search_recalls

Search FDA food enforcement (recall) records by product keyword.

Parameter	Type	Required	Description
product_name	string	Yes	Keyword to search in product descriptions
date_from	string	No	Start date filter (YYYY-MM-DD)
limit	integer	No	Max results (default 10, max 100)

Returns: recall_number, product_description, reason_for_recall, status, recall_initiation_date, recalling_firm, distribution_pattern, classification (Class I/II/III).

---

food_get_recall_detail

Retrieve the complete record for a specific recall by its FDA recall number.

Parameter	Type	Required	Description
recall_number	string	Yes	FDA recall number (e.g. F-0001-2024)

Returns: Full recall record including product_quantity, code_info, voluntary_mandated, firm address, and all standard recall fields.

---

food_search_adverse_events

Search FDA food adverse event reports by ingredient or brand name.

Parameter	Type	Required	Description
ingredient	string	Yes	Ingredient or brand keyword
date_from	string	No	Start date filter (YYYY-MM-DD)
limit	integer	No	Max results (default 10, max 100)

Returns: report_number, date_started, outcomes, reactions, products (with industry name), consumer demographics.

---

food_get_safety_alerts

Get the most recent FDA food safety alerts, optionally filtered by food category.

Parameter	Type	Required	Description
category	string	No	Food category: dairy, produce, meat, poultry, seafood, bakery, beverage, snack, supplement, nut, grain, spice, sauce, frozen, canned
limit	integer	No	Max results (default 10, max 100)

Returns: Alerts sorted by most-recent date with classification, recalling_firm, distribution_pattern.

---

Health Endpoint

GET /health
→ HTTP 200  {"status": "ok"}

Used by Apify and load balancers for liveness probes.

---

Quick Start

Local (stdio transport)

pip install -r requirements.txt
export OPENFDA_API_KEY=your_key_here   # optional
MCP_TRANSPORT=stdio python src/server.py

Local (SSE / HTTP transport)

pip install -r requirements.txt
python src/server.py
# Server runs on http://localhost:8080

Docker

docker build -f .actor/Dockerfile -t food-safety-mcp .
docker run -p 8080:8080 -e OPENFDA_API_KEY=your_key food-safety-mcp

Apify

Push to Apify using the Apify CLI:

apify login
apify push

Or deploy via the Apify Console by connecting this GitHub repository.

---

Environment Variables

Variable	Default	Description
OPENFDA_API_KEY	(none)	OpenFDA API key. Optional — falls back to anonymous tier (1 000 req/day/IP). Get one free.
PORT	8080	HTTP port for SSE transport
HOST	0.0.0.0	Bind address
MCP_TRANSPORT	sse	sse for HTTP, stdio for stdio MCP transport

---

Running Tests

pip install -r requirements.txt
pytest tests/ -v

---

Classification Guide

Class	Meaning
Class I	Reasonable probability of serious adverse health consequences or death
Class II	May cause temporary adverse health consequences; remote probability of serious risk
Class III	Unlikely to cause adverse health consequences

---

Data Source

All data is sourced from the OpenFDA API, a public API maintained by the U.S. Food and Drug Administration. Data is provided as-is; always verify critical safety information directly with the FDA.

• Food Enforcement: https://api.fda.gov/food/enforcement.json
• Food Adverse Events: https://api.fda.gov/food/event.json

---

License

MIT