Recipe MCP
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.
Ask AI about Recipe MCP
Powered by Claude Β· Grounded in docs
I know everything about Recipe MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.0httpx>=0.28.1aiofiles>=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:
- Open Claude Desktop and go to Settings
- Navigate to Connectors section
- Click Add Custom Connector
- Configure with the following details:
- Name:
Recipe Research MCP - URL:
https://recipe-mcp.onrender.com/mcp
- Name:
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=0o755for 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
PORTenvironment variable - Server binds to
0.0.0.0for 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.
