# Open Food Facts MCP Server
This is a Model Context Protocol (MCP) server implementation for Open Food Facts. It enables AI assistants to access food product information, providing nutritional analysis, product comparisons, and recipe suggestions using the official [Model Context Protocol](https://modelcontextprotocol.io/) specification.
### Benefits for Food-Aware Consumers
This MCP server enables:
1. **Nutritional Intelligence**: Get AI-powered analysis of food products and their health implications
2. **Informed Choices**: Compare products to make better dietary decisions
3. **Recipe Ideas**: Discover recipes based on products you have
4. **Dietary Support**: Understand allergens, additives, and dietary compatibility
## Available Tools
### Core Product Tools
- **searchProducts**: Search for products in the Open Food Facts database by name, brand, category, or other keywords
- **getProductByBarcode**: Get detailed information about a product by its barcode (EAN, UPC, etc.)
- **analyzeProduct**: Get AI-powered nutritional analysis of a food product
- **compareProducts**: Compare two products with AI-powered insights
- **suggestRecipes**: Get AI-powered recipe suggestions using a product
### Category & Search Tools
- **searchByCategory**: Search products within a specific food category (e.g., beverages, snacks, dairy, cereals)
- **searchByBrand**: Find all products from a specific brand
- **advancedSearch**: Advanced product search with multiple filters including category, brand, Nutri-Score, Eco-Score, NOVA group, allergen-free options, labels, and country
- **autocomplete**: Get autocomplete suggestions for categories, brands, labels, ingredients, allergens, or additives
### Nutrition & Health Tools
- **getNutriScore**: Get the Nutri-Score grade (A-E) for a product - quick health assessment at a glance
- **getEcoScore**: Get the Eco-Score (environmental impact rating A-E) for a product
- **getAdditivesInfo**: List all additives in a product with their E-numbers and NOVA processing level
- **getAllergenCheck**: Check if a product contains a specific allergen (gluten, milk, eggs, nuts, peanuts, soy, fish, shellfish, etc.)
- **checkMultipleAllergens**: Check if a product contains any of multiple allergens at once
### AI Insights Tools
- **getProductAIQuestions**: Get AI-generated questions about a product that need human verification
- **getRandomAIQuestions**: Get random AI-generated questions from Robotoff that need human verification - great for community contribution
- **getProductInsights**: Get AI-generated insights about products (detected labels, categories, ingredients issues, etc.)
- **getInsightTypes**: Get a summary of available AI insight types in Robotoff
### Price Tools
- **getProductPrices**: Get price history and current prices for a product from Open Prices
- **searchPrices**: Search for prices with filters (currency, country, date range)
- **getRecentPrices**: Get recently added prices to discover what's available
## Getting Started
### Prerequisites
- Node.js (v16.x or higher)
- npm or yarn
### Installation
1. Clone or download this repository
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
4. Start the server:
```bash
npm start
```
## Using with AI Assistants
### Claude Desktop
1. Start the MCP server:
```bash
npm start
```
2. Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"openfoodfacts": {
"command": "node",
"args": ["/path/to/OpenFoodFacts-MCP/dist/index.js"],
"env": {
"TRANSPORT": "stdio"
}
}
}
}
```
### VS Code with GitHub Copilot
1. Install the "Model Context Protocol" extension for VS Code
2. Create `.vscode/mcp.json`:
```json
{
"servers": {
"openfoodfacts": {
"command": "node",
"args": ["${workspaceFolder}/dist/cli.js"],
"env": {
"TRANSPORT": "stdio"
}
}
}
}
```
### Other AI Tools
The server supports HTTP/SSE transport for browser-based AI tools:
```bash
TRANSPORT=http PORT=3000 npm start
```
Then connect your AI tool to `http://localhost:3000/sse`
## Example Conversations
Here are natural ways to ask your AI assistant to use the Open Food Facts tools:
### Searching for Products
- "Search for chocolate cereals in the Open Food Facts database"
- "Find products that contain almond milk"
- "Look for organic yogurt products"
### Getting Product Details
- "Get information about the product with barcode 3017620422003"
- "What's in the product with EAN 5000159407236?"
- "Show me nutritional data for barcode 8076809513326"
### Analyzing Products
- "Can you analyze Nutella nutritionally?"
- "Analyze Cheerios cereal and tell me if it's healthy"
- "Give me a health analysis of Oreo cookies"
- "Is the product with barcode 3017620422003 healthy?"
### Comparing Products
- "Compare Nutella and Nocciolata"
- "Which is healthier: Coke or Pepsi?"
- "Compare almond milk and soy milk nutritionally"
- "Compare the products with barcodes 3017620422003 and 5000159407236"
### Recipe Suggestions
- "What can I make with Greek yogurt?"
- "Suggest some recipes using chickpeas"
- "Give me recipe ideas for quinoa"
- "What recipes can I make with the product 3017620422003?"
### Category & Brand Searches
- "Show me all products in the beverages category"
- "Find all Nestlé products"
- "Search for organic products with Nutri-Score A"
- "Find vegan snacks with good Eco-Score"
### Allergen Checks
- "Does Nutella contain gluten?"
- "Check if this product is safe for someone allergic to milk and eggs"
- "Is barcode 3017620422003 peanut-free?"
- "What allergens are in Cheerios?"
### Price Lookups
- "What's the current price of Nutella?"
- "Show me recent prices for products in France"
- "Compare prices for barcode 3017620422003"
## Resources and Prompts
The MCP server provides helpful resources and prompts:
### Resources
The server provides educational resources to help you understand food data:
- **Quick Help Guide**: How to use the Open Food Facts tools - quick reference
- **Nutri-Score Guide**: Understanding Nutri-Score health ratings (A-E)
- **Eco-Score Guide**: Understanding Eco-Score environmental ratings (A-E)
- **Allergens Reference**: Common food allergens and where they hide
- **Food Additives Guide**: Understanding E-numbers and food additives
- **NOVA Processing Guide**: Understanding food processing levels (1-4)
### Prompts
Pre-configured prompts help you get started quickly:
- **analyze-product**: Get detailed nutritional analysis
- **compare-products**: Compare two products side-by-side
- **find-healthy-alternatives**: Find healthier alternatives to a product
- **check-allergens**: Check if a product is safe for your allergies
- **whats-for-dinner**: Get recipe ideas using a product
## How It Works
The MCP server acts as a bridge between AI assistants and the Open Food Facts database:
1. **Your Question**: You ask your AI assistant about food products
2. **Tool Detection**: The AI recognizes it needs Open Food Facts data
3. **MCP Request**: The AI calls the appropriate MCP tool
4. **Data Retrieval**: The server fetches data from Open Food Facts
5. **AI Analysis**: The AI processes the data and responds to you
## Example Workflows
### Making Healthier Choices
```
You: "Is Nutella healthy?"
AI Assistant uses:
1. searchProducts to find Nutella
2. getProductByBarcode with the barcode
3. analyzeProduct for nutritional assessment
Response: Detailed analysis of Nutella's nutritional profile,
health scores, ingredients, and dietary considerations
```
### Comparing Options
```
You: "Which is better for me, Nutella or almond butter?"
AI Assistant uses:
1. searchProducts for both products
2. compareProducts with both barcodes
Response: Side-by-side comparison with recommendations
based on your dietary needs
```
### Recipe Planning
```
You: "What can I make with Greek yogurt?"
AI Assistant uses:
1. searchProducts to find Greek yogurt
2. suggestRecipes with the product
Response: Recipe suggestions that use Greek yogurt
as an ingredient
```
## Technical Details
### Server Architecture
The server follows a modular architecture for maintainability and scalability:
**Core Server**
- `src/index.ts`: Entry point
- `src/server.ts`: Core MCP server implementation with resource and prompt registration
- `src/cli.ts`: CLI interface for development
**Tools (Modular Design)**
- `src/tools/index.ts`: Tool registration orchestrator and core product tools
- `src/tools/product-search.ts`: Product search and barcode lookup utilities
- `src/tools/category-tools.ts`: Category and brand search tools
- `src/tools/nutrition-tools.ts`: Nutrition scores, allergen checks, and additive information
- `src/tools/insights-tools.ts`: AI-generated insights from Robotoff
- `src/tools/price-tools.ts`: Product pricing data from Open Prices
- `src/tools/types.ts`: Shared type definitions and interfaces
- `src/tools/helpers.ts`: Reusable helper functions for all tools
**Resources & Services**
- `src/resources/`: Resource handlers for guides and documentation
- `resource-registry.ts`: Resource registration system
- `static-resources.ts`: Static resource content (guides, references)
- `src/sampling/`: AI model integration for analysis and recipe generation
- `sampling-service.ts`: MCP sampling integration for AI-powered features
**Infrastructure**
- `src/transport/`: Communication layer (stdio for CLI/editors, HTTP for browsers)
- `src/config/`: Server configuration
### Data Source
All product data comes from [Open Food Facts](https://world.openfoodfacts.org/), a free, open, collaborative database of food products from around the world.
## Troubleshooting
### Server Won't Start
- Ensure Node.js v16+ is installed
- Run `npm install` to install dependencies
- Check that port 3000 is available (for HTTP mode)
### AI Can't Find Tools
- Verify the MCP server is running
- Check your AI assistant's MCP configuration
- Ensure the transport type matches (stdio vs HTTP)
### Product Not Found
- Try searching first with `searchProducts`
- Verify the barcode is correct (8-14 digits)
- Some products may not be in the database yet
### Slow Responses
- The server fetches real-time data from Open Food Facts
- First requests may be slower as data is retrieved
- Internet connection speed affects performance
## Contributing
We welcome contributions! You can help by:
- Adding support for more food databases
- Improving AI analysis prompts
- Enhancing error handling
- Adding new tools for dietary tracking
- Improving documentation
## About Open Food Facts
Open Food Facts is a food products database made by everyone, for everyone. It's a collaborative project that collects information about food products from around the world, including:
- Ingredients
- Nutritional facts
- Allergens
- Environmental impact
- Health scores (Nutri-Score, NOVA)
Learn more at [https://world.openfoodfacts.org/](https://world.openfoodfacts.org/)
## License
This project is licensed under the GNU Affero General Public License v3.0, consistent with the Open Food Facts project.
## Support
- Open Food Facts Website: https://world.openfoodfacts.org/
- Open Food Facts GitHub: https://github.com/openfoodfacts
- Model Context Protocol: https://modelcontextprotocol.io/
---
**Made with care for food-aware consumers everywhere**
