Open Food Facts MCP

🚀 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: Retrieve detailed information by barcode, including nutritional facts, ingredients, and scores.
• Smart Search: Find products using 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: Suitable for 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

📦 Installation

The installation steps are provided in the "Quick Start" section, including Docker deployment and local development setups.

💻 Usage 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)

📚 Documentation

🔧 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.

🔧 Technical Details

🧪 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.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Make your changes with tests.
4. Run quality checks (npm run validate).
5. Commit your changes (git commit -m 'Add amazing feature').
6. Push to the branch (git push origin feature/amazing-feature).
7. 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.

💡 Usage Tip

If you need help, open an issue or check the examples for detailed usage patterns.