<h1 align="center">Food Data Central MCP Server</h1>
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for accessing the USDA's FoodData Central database. This server provides AI agents with the ability to search for foods, get detailed nutritional information, and access comprehensive food data from the USDA's database.
## Overview
This project demonstrates how to build an MCP server that enables AI agents to access the USDA FoodData Central API. It allows searching for foods, retrieving detailed nutritional information, and accessing comprehensive food data through keyword search and structured queries.
This project is based on Cole Medin's excellent [MCP-Mem0 project](https://github.com/coleam00/mcp-mem0) and jlfwong's [Food Data Central MCP Server](https://github.com/jlfwong/food-data-central-mcp-server).
## Features
The server provides three essential food data access tools:
1. **`search_foods`**: Search for foods using keywords with optional filters for data type, brand, date range, etc.
2. **`get_food_details`**: Get comprehensive nutritional and ingredient information for a specific food item by FDC ID
3. **`get_multiple_foods`**: Retrieve detailed information for multiple foods at once (up to 20 items)
## Prerequisites
- Python 3.12+
- USDA API key (free from [FoodData Central](https://fdc.nal.usda.gov/api-guide.html))
- Docker if running the MCP server as a container (recommended)
## Installation
### Using uv
1. Install uv if you don't have it:
```bash
pip install uv
```
2. Clone this repository:
```bash
git clone https://github.com/FelipeAdachi/mcp-food-data-central.git
cd food-data-central-mcp
```
3. Create a virtual environment:
```bash
uv venv
```
4. Install dependencies:
```bash
uv pip install -e .
```
5. Create a `.env` file based on `env.example`:
```bash
cp env.example .env
```
6. Configure your environment variables in the `.env` file (see Configuration section)
### Using Docker (Recommended)
1. Build the Docker image:
```bash
docker build -t food-data-central-mcp --build-arg PORT=8050 .
```
2. Create a `.env` file based on `env.example` and configure your environment variables
## Configuration
The following environment variables can be configured in your `.env` file:
| Variable | Description | Example |
|----------|-------------|----------|
| `USDA_API_KEY` | Your USDA FoodData Central API key | `your_api_key_here` |
| `TRANSPORT` | Transport protocol (sse or stdio) | `sse` |
| `HOST` | Host to bind to when using SSE transport | `0.0.0.0` |
| `PORT` | Port to listen on when using SSE transport | `8050` |
## Getting Your API Key
1. Visit the [USDA FoodData Central API Guide](https://fdc.nal.usda.gov/api-guide.html)
2. Sign up for a free API key
3. Add the key to your `.env` file as `USDA_API_KEY`
## Running the Server
### Using uv
#### SSE Transport
```bash
# Set TRANSPORT=sse in .env then:
uv run src/main.py
```
The MCP server will essentially be run as an API endpoint that you can then connect to with config shown below.
#### Stdio Transport
With stdio, the MCP client itself can spin up the MCP server, so nothing to run at this point.
### Using Docker
#### SSE Transport
```bash
docker run --env-file .env -p 8050:8050 food-data-central-mcp
```
The MCP server will essentially be run as an API endpoint within the container that you can then connect to with config shown below.
#### Stdio Transport
With stdio, the MCP client itself can spin up the MCP server container, so nothing to run at this point.
## Integration with MCP Clients
### SSE Configuration
Once you have the server running with SSE transport, you can connect to it using this configuration:
```json
{
"mcpServers": {
"food-data-central": {
"transport": "sse",
"url": "http://localhost:8050/sse"
}
}
}
```
> **Note for Windsurf users**: Use `serverUrl` instead of `url` in your configuration:
> ```json
> {
> "mcpServers": {
> "food-data-central": {
> "transport": "sse",
> "serverUrl": "http://localhost:8050/sse"
> }
> }
> }
> ```
> **Note for n8n users**: Use host.docker.internal instead of localhost since n8n has to reach outside of its own container to the host machine:
>
> So the full URL in the MCP node would be: http://host.docker.internal:8050/sse
Make sure to update the port if you are using a value other than the default 8050.
### Python with Stdio Configuration
Add this server to your MCP configuration for Claude Desktop, Windsurf, or any other MCP client:
```json
{
"mcpServers": {
"food-data-central": {
"command": "your/path/to/food-data-central-mcp/.venv/Scripts/python.exe",
"args": ["your/path/to/food-data-central-mcp/src/main.py"],
"env": {
"TRANSPORT": "stdio",
"USDA_API_KEY": "YOUR-API-KEY"
}
}
}
}
```
### Docker with Stdio Configuration
```json
{
"mcpServers": {
"food-data-central": {
"command": "docker",
"args": ["run", "--rm", "-i",
"-e", "TRANSPORT",
"-e", "USDA_API_KEY",
"food-data-central-mcp"],
"env": {
"TRANSPORT": "stdio",
"USDA_API_KEY": "YOUR-API-KEY"
}
}
}
}
```
## Usage Examples
### Searching for Foods
```python
# Search for cheese products
search_foods(query="cheddar cheese", page_size=10)
# Search for branded foods from a specific company
search_foods(query="yogurt", data_type=["Branded"], brand_owner="Dannon")
# Search with date filtering
search_foods(query="organic apple", start_date="2023-01-01", end_date="2023-12-31")
```
### Getting Food Details
```python
# Get full details for a specific food item
get_food_details(fdc_id=534358)
# Get abridged details with specific nutrients only
get_food_details(fdc_id=534358, format_type="abridged", nutrients=[203, 204, 205])
```
### Getting Multiple Foods
```python
# Get details for multiple foods at once
get_multiple_foods(fdc_ids=[534358, 373052, 616350])
```
## API Reference
The server provides access to the USDA FoodData Central API endpoints:
- **Search Foods** (`/v1/foods/search`)
- **Food Details** (`/v1/food/{fdcId}`)
- **Multiple Foods** (`/v1/foods`)
All data returned follows the official USDA FoodData Central API schema and includes comprehensive nutritional information, ingredients, serving sizes, and more.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
