Open Food Facts MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to the Open Food Facts database. Query detailed food product information, nutritional data, and environmental scores to help users make informed food choices.

🌟 Features

Product Lookup: Get detailed information by barcode including nutritional facts, ingredients, and scores
Smart Search: Find products with advanced filtering by categories, brands, nutrition grades, and more
Nutritional Analysis: Interpret Nutri-Score, NOVA processing groups, and Eco-Score ratings
Product Comparison: Compare multiple products side-by-side across different criteria
Dietary Recommendations: Get suggestions based on dietary preferences and restrictions
Rate Limiting: Built-in rate limiting respects Open Food Facts API constraints
Docker Ready: Production deployment with Docker and Docker Compose

🚀 Quick Start

Docker Deployment (Recommended)

# Clone and run
git clone https://github.com/conner/open-food-facts-mcp
cd open-food-facts-mcp
docker-compose up --build

Local Development

# Install dependencies
npm install

# Configure environment
cp .env.example .env

# Build and start
npm run build
npm start

# Development mode
npm run dev

🔧 Configuration

Configure the server via environment variables:

# API Configuration
OPEN_FOOD_FACTS_BASE_URL=https://world.openfoodfacts.net
OPEN_FOOD_FACTS_USER_AGENT=YourApp/1.0 (contact@example.com)

# Rate Limits (requests per minute)
RATE_LIMIT_PRODUCTS=100
RATE_LIMIT_SEARCH=10
RATE_LIMIT_FACETS=2

🛠 Available Tools

`get_product`

Retrieve comprehensive product information by barcode.

{
  "barcode": "3017620422003"
}

Returns: Product name, brand, nutritional scores, ingredients, nutrition facts, and metadata.

`search_products`

Search products with advanced filtering capabilities.

{
  "search": "organic chocolate",
  "categories": "snacks",
  "nutrition_grades": "a,b,c",
  "page_size": 10
}

Filters: Categories, brands, countries, nutrition grades, NOVA groups, sorting options.

`analyze_product`

Get detailed nutritional analysis and score interpretations.

{
  "barcode": "3017620422003"
}

Returns: Score explanations, nutritional breakdown with health assessments, and processing level details.

`compare_products`

Compare multiple products across different aspects.

{
  "barcodes": ["3017620422003", "8712566073219"],
  "focus": "nutrition"
}

Focus Options: nutrition, environmental, processing, ingredients.

`get_product_suggestions`

Get personalized product recommendations.

{
  "category": "beverages",
  "dietary_preferences": ["vegan", "organic"],
  "min_nutriscore": "b",
  "max_results": 5
}

Dietary Options: vegan, vegetarian, gluten-free, organic, low-fat, low-sugar, high-protein.

🤖 MCP Integration

Add to your MCP client configuration:

{
  "mcpServers": {
    "open-food-facts": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "open-food-facts-mcp"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "open-food-facts": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/open-food-facts-mcp"
    }
  }
}

📊 Data & Scores

Nutri-Score

A-E rating indicating overall nutritional quality
Green (A/B): Healthier choices
Red (D/E): Less healthy options

NOVA Groups

Group 1: Unprocessed/minimally processed foods
Group 2: Processed culinary ingredients
Group 3: Processed foods
Group 4: Ultra-processed foods

Eco-Score

A-E rating for environmental impact
Considers packaging, transportation, and production methods

🧪 Development

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Validate code quality
npm run validate

Code Quality

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

Project Structure

src/
├── client.ts       # HTTP client with rate limiting
├── handlers.ts     # MCP tool implementations
├── index.ts        # MCP server entry point
├── tools.ts        # Tool definitions
└── types.ts        # TypeScript types and schemas

tests/
├── client.test.ts      # Client unit tests
├── handlers.test.ts    # Handler unit tests
├── server.test.ts      # Integration tests
├── validation.test.ts  # Schema validation tests
├── rate-limiting.test.ts # Rate limiting tests
├── e2e.test.ts        # End-to-end tests
├── fixtures/          # Test data
└── utils/            # Test utilities

📈 Performance

Rate Limiting: Automatic enforcement of API limits
Efficient Caching: Smart request deduplication
Batch Operations: Optimized multi-product comparisons
Error Recovery: Graceful handling of API failures

🔒 API Limits

The server respects Open Food Facts API rate limits:

Product queries: 100 requests/minute
Search queries: 10 requests/minute
Facet queries: 2 requests/minute

Rate limits are enforced automatically with proper error messaging.

🌍 Data Source

All data comes from Open Food Facts, the largest open food database in the world:

900,000+ products from 150+ countries
Collaborative data maintained by contributors worldwide
Open Database License ensuring free access to food information
Real-time updates from the global community

📝 Examples

Basic Product Information

**Nutella**
Brand: Ferrero
Quantity: 400g
Categories: Sweet spreads, Chocolate spreads

Scores:
Nutri-Score: E | NOVA Group: 4 | Eco-Score: D

Ingredients:
Sugar, palm oil, hazelnuts (13%), skimmed milk powder...

Nutrition (per 100g):
Energy: 539 kcal | Fat: 30.9g | Carbs: 57.5g | Sugars: 56.3g

Nutritional Analysis

Nutritional Analysis: Nutella

Scores:
• Nutri-Score E: Very poor nutritional quality
• NOVA Group 4: Ultra-processed foods  
• Eco-Score D: High environmental impact

Nutritional Breakdown:
• Energy: 539 kcal (high)
• Fat: 30.9g (high)
• Sugars: 56.3g (high)
• Salt: 0.107g (low)

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Run quality checks (npm run validate)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Open Food Facts for providing the comprehensive food database
Model Context Protocol for the MCP specification
The global community of contributors maintaining food data quality

Need help? Open an issue or check the examples for detailed usage patterns.