suraj-yadav-aiml/recipe-mcp

Recipe Research MCP Server

A comprehensive Model Context Protocol (MCP) server that provides recipe search, storage, and meal planning functionality using TheMealDB API. Built with FastMCP and designed for both local development and remote deployment.

🚀 Features

🔍 Recipe Search & Discovery

• Search recipes by dish name or cuisine
• Find recipes starting with specific letters
• Get random recipe suggestions
• Detailed recipe information with ingredients, instructions, and metadata

📊 Recipe Management

• Automatic recipe storage and indexing
• Fast recipe lookup system
• Recipe collection organization by cuisine/dish type
• Cross-platform file handling with proper sanitization

🍽️ Meal Planning

• Create custom meal plans from selected recipes
• Save and manage multiple meal plans
• Recipe collection statistics and insights

🎯 MCP Integration

• Tools: Interactive recipe search and meal planning functions
• Resources: Read-only access to recipe collections and statistics
• Prompts: Pre-defined templates for cooking education and analysis

📋 Requirements

• Python: 3.12 or higher
• Package Manager: UV (recommended)
• Dependencies:
  • mcp[cli]>=1.15.0
  • httpx>=0.28.1
  • aiofiles>=24.1.0

🛠️ Installation

Using UV (Recommended)

# Clone the repository
git clone https://github.com/suraj-yadav-aiml/recipe-mcp.git
cd recipe-mcp

# Create and activate virtual environment
uv venv
# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

# Install dependencies
uv sync

# Test the MCP Server
mcp dev recipe_server.py

Using pip

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Test the MCP Server
mcp dev recipe_server.py

🚀 Usage

Local Development (STDIO Transport)

if __name__ == "__main__":
    mcp.run(transport="stdio") 

Remote Deployment (HTTP Transport)

if __name__ == "__main__":
    mcp.run(transport="streamable-http") 

MCP Client Configuration

Option 1: Remote MCP Server (Recommended)

Add to Claude Desktop as Custom Connector:

1. Open Claude Desktop and go to Settings
2. Navigate to Connectors section
3. Click Add Custom Connector
4. Configure with the following details:
   • Name: Recipe Research MCP
   • URL: https://recipe-mcp.onrender.com/mcp

This connects to our hosted Recipe MCP server without any local setup required.

Option 2: Local MCP Server

Add to your MCP client configuration file:

{
  "recipe_research": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli]",
      "httpx",
      "aiofiles",
      "mcp",
      "run",
      "path/to/recipe_server.py"
    ],
    "cwd": "path/to/project",
    "env": {
      "PYTHONPATH": "path/to/project"
    }
  }
}

Or for Windows:

{
  "recipe_research": {
    "command": "C:\\Users\\Admin\\.local\\bin\\uv.EXE",
    "args": [
      "--directory",
      "path/to/project",
      "run",
      "path/to/project/recipe_server.py"
    ]
  }
}

🔧 API Reference

Tools

search_recipes(dish_name: str, max_results: int = 5)

Search for recipes by dish name using TheMealDB API.

Example:

# Search for pasta recipes
results = await search_recipes("pasta", max_results=10)

get_recipe_details(recipe_id: str)

Get detailed information about a specific recipe by ID.

Example:

# Get details for recipe ID 52771
details = await get_recipe_details("52771")

create_meal_plan(recipe_ids: List[str], plan_name: str = "My Meal Plan")

Create a meal plan from selected recipe IDs.

Example:

# Create a meal plan
plan = await create_meal_plan(
    ["52771", "52772", "52773"],
    "Italian Week"
)

search_by_first_letter(letter: str, max_results: int = 5)

Search for recipes that start with a specific letter.

Example:

# Find recipes starting with 'A'
results = await search_by_first_letter("A")

get_random_recipe()

Get a random recipe from TheMealDB.

Resources

recipes://cuisines

List all available recipe collections in the database.

recipes://{cuisine}

Get detailed information about recipes in a specific cuisine collection.

Example: recipes://italian, recipes://pasta

recipes://meal-plans

View all saved meal plans with their details.

recipes://stats

Get comprehensive statistics about the recipe collection.

Prompts

generate_recipe_search_prompt(cuisine_type: str, num_recipes: int = 5)

Generate a comprehensive prompt for recipe search and culinary analysis.

generate_meal_planning_prompt(meal_type: str, people_count: int = 4, dietary_restrictions: str = "none")

Create a detailed meal planning prompt with shopping lists and preparation guides.

generate_cooking_lesson_prompt(skill_level: str, technique_focus: str, cuisine_style: str = "any")

Design structured cooking lessons focused on specific techniques.

generate_ingredient_exploration_prompt(main_ingredient: str, cooking_styles: str = "diverse", num_recipes: int = 6)

Explore recipes and techniques featuring a specific ingredient.

generate_cultural_cuisine_prompt(cuisine_name: str, cultural_context: str = "traditional", num_recipes: int = 5)

Explore the cultural heritage and traditions of specific cuisines.

📁 Data Structure

recipes/
├── <dish_name>/
│   └── recipes_info.json          # Recipe details by dish/cuisine
├── meal_plans/
│   └── <plan_name>.json          # Saved meal plans
├── by_letter/
│   └── letter_<x>_search.json    # Letter-based searches
└── recipe_index.json             # Master recipe index

Recipe Data Format

{
  "recipe_id": {
    "name": "Recipe Name",
    "cuisine": "Italian",
    "category": "Pasta",
    "instructions": "Step by step instructions...",
    "image_url": "https://...",
    "youtube_url": "https://...",
    "source_url": "https://...",
    "ingredients": [
      {
        "ingredient": "Tomatoes",
        "measure": "400g"
      }
    ],
    "tags": ["Vegetarian", "Quick"]
  }
}

🌐 API Integration

This server integrates with TheMealDB free API:

• Base URL: https://www.themealdb.com/api/json/v1/1
• Search by name: /search.php?s={dish_name}
• Search by letter: /search.php?f={letter}
• Random recipe: /random.php

No API key required for the free tier.

🔧 Development

Code Standards

• Async/Await: All I/O operations use asyncio and aiofiles
• HTTP Requests: Use httpx for all web requests
• Path Handling: Use Pathlib for cross-platform compatibility
• Error Handling: Comprehensive but not verbose
• Concurrency: Use asyncio.gather() for parallel operations
• No Logging: Code should not include logging statements

File Operations

• All JSON files use UTF-8 encoding with ensure_ascii=False
• Directory creation uses mode=0o755 for cross-platform compatibility
• Filename sanitization removes invalid characters for Windows/Mac/Linux compatibility
• Recipe index automatically rebuilds when stale entries are detected

Deployment

Local Development

• Uses STDIO transport by default
• Suitable for MCP client integration

Remote Deployment

• Set PORT environment variable
• Server binds to 0.0.0.0 for external access
• Uses streamable HTTP transport

📊 Performance Features

• Concurrent Operations: Recipe processing uses asyncio.gather()
• Caching: Recipe index provides fast lookups
• Lazy Loading: Resources load data on-demand
• Cross-platform: Handles Windows, Mac, and Linux file systems

📄 License

This project is part of an Educational MCP server implementation.

🔗 Related Links

• Model Context Protocol Documentation
• FastMCP Framework
• TheMealDB API
• UV Package Manager