mealie-mcp
Provides a full-featured MCP server with 27 tools to manage recipes, shopping lists, meal plans, organizers, foods, and units via the Mealie API. Includes dietary guardrails, skills, agents, and slash commands for family-centered recipe management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mealie-mcp find a healthy chicken recipe without seed oils"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mealie Plugin for Claude Code
A Claude Code plugin that bundles a full-featured Mealie MCP server (27 tools) with skills, agents, and commands for family-centered recipe management, homesteading cooking guidance, and dietary compliance.
Maintained by Thrivewell Partners
Features
27-tool MCP server — Direct access to Mealie's recipes, shopping lists, meal plans, organizers, foods, and units
5 Claude Code skills — Auto-activating knowledge libraries for recipe creation, Foundation recipes, dietary management, cooking tips, and meal planning
3 intelligent agents — Recipe advisor, meal planner, and cooking teacher — auto-triggered on relevant conversations
3 slash commands —
/mealie:quick-recipe,/mealie:weekly-menu,/mealie:find-recipeDietary guardrail hook — Scans ingredients for pork products and seed oils before any recipe is saved to Mealie
Family-aware defaults — Serves 6, mild heat, no pork, no seed oils throughout all components
Related MCP server: mealie-mcp-server
Installation
As a Claude Code Plugin (Recommended)
1. Add the Marketplace
/plugin marketplace add https://github.com/thrivewell-partners/mealie-mcp2. Install the Plugin
/plugin install mealie@thrivewell-marketplace3. Set Environment Variables
export MEALIE_URL="https://your-mealie-instance.com"
export MEALIE_API_KEY="your-api-token"Get your API token: Mealie UI → User Profile → API Tokens → Generate
4. Restart Claude Code — MCP server and hooks load on startup.
Standalone MCP Server (Advanced / Development)
1. Install
git clone https://github.com/thrivewell-partners/mealie-mcp
cd mealie-mcp
uv pip install -e .2. Configure
# Create .env file with your Mealie credentials
echo "MEALIE_URL=https://your-mealie-instance.com" > .env
echo "MEALIE_API_KEY=your-api-token" >> .env3. Add to Claude Code MCP settings
In .claude/settings.json or your project's MCP config:
{
"mcpServers": {
"mealie": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mealie-mcp", "mealie-mcp"],
"env": {
"MEALIE_URL": "https://your-mealie-instance.com",
"MEALIE_API_KEY": "your-api-token"
}
}
}
}Plugin Components
Skills (Auto-Activated)
Skills load automatically when you ask related questions — no command needed.
Skill | Trigger Phrases | Description |
| "add a recipe", "create a recipe for [dish]", "save this recipe to Mealie" | Structured Mealie v3 recipe authoring with family defaults |
| "foundation recipe", "the why behind the how", "educational recipe" | Educational Foundation recipe paradigm with full technique documentation |
| "check for dietary issues", "substitute the oil", "is this family-friendly" | Compliance checking, pork/seed-oil detection, substitution guidance |
| "how do I braise", "homesteading cooking", "what is fond", "how to render tallow" | Scratch cooking techniques with food science explanations |
| "plan meals for the week", "weekly menu", "what should we eat" | Weekly meal planning via Mealie API |
Agents
Agent | Color | Triggers | Role |
| Green | Recipe modification discussions, dietary evaluation, substitution requests | Read-only recipe consultant — evaluates and advises |
| Blue | "Plan the week's meals", "fill in the meal plan", multi-day meal requests | Drafts weekly menus, gets approval, creates Mealie entries |
| Cyan | "Teach me how to", technique questions, troubleshooting cooking failures | Explains the science and technique behind cooking methods |
Commands
Command | Usage | Description |
|
| Guided step-by-step recipe creation into Mealie |
|
| Plan a week of dinners, get approval, create Mealie entries |
|
| Search with dietary context and direct actions |
Dietary Guardrail Hook
A PreToolUse hook fires before every create_recipe and update_recipe MCP call. It uses a Claude prompt to scan the ingredients list for:
Pork products: bacon, ham, lard, prosciutto, pork sausage, chorizo, carnitas, and all variants
Seed oils: canola, vegetable, sunflower, safflower, corn, soybean, cottonseed, grapeseed, rice bran oils
If violations are found, Claude receives a warning with the specific ingredient names and suggested compliant alternatives. The operation is not blocked — Claude decides whether to correct and retry or proceed.
Family Dietary Guidelines
These rules are enforced by all plugin components:
NO PORK
No pork or pork-derived products. This includes: pork chops, bacon, ham, lard, prosciutto, pancetta, guanciale, salami, pepperoni, pork sausage, carnitas, pork ribs, pork belly, pork rinds, fatback.
NO SEED OILS
No industrially extracted seed or vegetable oils. Forbidden: vegetable oil, canola oil, sunflower oil, safflower oil, corn oil, soybean oil, cottonseed oil, grapeseed oil, rice bran oil, margarine.
Compliant fats: avocado oil · tallow · ghee · butter · olive oil · coconut oil · duck fat
SCALE FOR 6
Default all recipes to serve 6 people. Numeric servings field enables Mealie's scaling feature.
MILD TO MODERATE HEAT
Kid-friendly heat. Jalapeños seeded. No habaneros, scotch bonnets, or super-hot chilis.
MCP Server Tools (27)
Recipes
Tool | Description |
| Search by keyword with category/tag filters |
| Full recipe detail including ingredients, instructions, nutrition, notes |
| Ingredient list only |
| Import from URL (Mealie scrapes automatically) |
| Create manually with full structured content |
| Update any fields on an existing recipe |
| Permanently delete a recipe |
Shopping Lists
Tool | Description |
| List all shopping lists |
| View list with all items (checked/unchecked) |
| Create new empty list |
| Delete a list |
| Add item to a list |
| Remove item from a list |
| Check or uncheck an item |
| Add all recipe ingredients to a list |
Meal Plans
Tool | Description |
| View plans for a date range |
| Add entry (recipe or freeform) for a date |
| Remove an entry |
| Auto-fill date range with random recipes |
Organizers
Tool | Description |
| List all recipe categories |
| List all tags |
| List all cookbooks |
| Recipes in a specific cookbook |
| Create a new category |
| Create a new tag |
Foods & Units
Tool | Description |
| Search Mealie's foods database |
| List all measurement units |
Requirements
Python 3.11+
uv package manager
Mealie v3.0+ — self-hosted recipe manager
Claude Code with plugin support
Development
Run Tests
uv run pytestProject Structure
mealie-mcp/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── marketplace.json # GitHub Marketplace directory
├── src/mealie_mcp/ # MCP server source
│ ├── server.py # FastMCP app and tool registration
│ ├── client.py # Async Mealie API client (httpx)
│ ├── config.py # Pydantic settings (MEALIE_URL, MEALIE_API_KEY)
│ ├── formatting.py # Markdown output formatters
│ └── tools/ # Tool modules
│ ├── recipes.py # 7 recipe tools
│ ├── shopping.py # 8 shopping list tools
│ ├── mealplan.py # 4 meal plan tools
│ ├── organizers.py # 6 organizer tools
│ └── foods.py # 2 food/unit tools
├── skills/ # Claude Code skills
│ ├── recipe-creation/ # Mealie v3 recipe authoring
│ ├── foundations/ # Foundation recipe paradigm
│ ├── dietary-management/ # Compliance and substitutions
│ ├── cooking-tips/ # Homesteading techniques
│ └── meal-planning/ # Weekly planning workflow
├── agents/ # Claude Code agents
│ ├── recipe-advisor.md # Recipe evaluation and adaptation
│ ├── meal-planner.md # Weekly meal planning
│ └── cooking-teacher.md # Technique education
├── commands/ # Slash commands
│ ├── quick-recipe.md # Guided recipe creation
│ ├── weekly-menu.md # Weekly meal plan
│ └── find-recipe.md # Recipe search
├── hooks/
│ └── hooks.json # Dietary guardrail PreToolUse hook
├── tests/ # Test suite (pytest + respx)
├── .mcp.json # MCP server config (env var references)
└── pyproject.toml # Python project metadataLicense
MIT
Available Tools
27 toolsadd_recipe_to_shopping_listB
Add all ingredients from a recipe to a shopping list.
Args: list_id: Shopping list ID recipe_slug: Recipe slug to add ingredients from
Inputs: list_id (required), recipe_slug (required). Returns: result
add_shopping_list_itemB
Add an item to a shopping list.
Args: list_id: Shopping list ID note: Item description (e.g. "2 lbs chicken breast") quantity: Numeric quantity (optional, for structured items) unit_id: Unit ID from get_units (optional) food_id: Food ID from search_foods (optional)
Inputs: note (required), list_id (required), food_id, unit_id, +1 more. Returns: result
check_shopping_list_itemA
Check or uncheck a shopping list item.
Args: list_id: Shopping list ID item_id: Item ID to check/uncheck checked: True to check, False to uncheck (default True)
Inputs: item_id (required), list_id (required), checked. Returns: result
create_categoryA
Create a new recipe category.
Args: name: Category name
Inputs: name (required). Returns: result
create_meal_plan_entryA
Add a meal plan entry for a specific date.
Args: date: Date for the entry (YYYY-MM-DD) entry_type: Meal type — "breakfast", "lunch", "dinner", or "side" recipe_slug: Recipe slug to plan (use this OR title/note) title: Free-text title (for non-recipe entries) note: Additional note text
Inputs: date (required), note, title, entry_type, +1 more. Returns: result
create_recipeA
Create a new recipe manually.
Args: name: Recipe name description: Short description recipe_yield: Yield description (e.g. "15–18 rolls", "1 loaf") servings: Numeric serving count that enables scaling (e.g. 6, 8, 15) total_time: Total time (e.g. "45 minutes") prep_time: Prep time perform_time: Cook time ingredients: List of ingredient dicts, each with optional keys: - section (str): creates a visual section header (no other fields used) - quantity (float): numeric amount (e.g. 300, 2.5) - unit (str): unit name or abbreviation (e.g. "g", "cup", "tbsp") - food (str): ingredient name (e.g. "bread flour", "butter") - comment (str): extra info shown alongside (e.g. "softened", "about 1¾ tsp") instructions: List of instruction steps — each may be a plain string or a dict with: - text (str): step body - title (str, optional): step heading shown in UI - summary (str, optional): one-line takeaway for cook mode - ingredient_refs (list[str], optional): UUIDs of linked ingredients categories: Category names to assign tags: Tag names to assign notes: List of note dicts, each with: - title (str): section label (e.g. "Non-Negotiables") - text (str): note body extras: Arbitrary JSON metadata (e.g. {"isFoundation": true})
Inputs: name (required), tags, notes, extras, +9 more. Returns: result
create_recipe_from_urlA
Import a recipe by scraping a URL. Mealie will extract the recipe data automatically.
Args: url: URL of the recipe page to import
Inputs: url (required). Returns: result
create_shopping_listB
Create a new empty shopping list.
Args: name: Name for the new list
Inputs: name (required). Returns: result
create_tagA
Create a new recipe tag.
Args: name: Tag name
Inputs: name (required). Returns: result
delete_meal_plan_entryA
Remove a meal plan entry.
Args: entry_id: Meal plan entry ID (from get_meal_plans)
Inputs: entry_id (required). Returns: result
delete_recipeA
Delete a recipe permanently.
Args: slug: Recipe slug to delete
Inputs: slug (required). Returns: result
delete_shopping_listC
Delete a shopping list.
Args: list_id: Shopping list ID to delete
Inputs: list_id (required). Returns: result
generate_random_meal_planA
Auto-fill a date range with random recipes from your collection.
Args: start_date: Start date (YYYY-MM-DD) end_date: End date (YYYY-MM-DD) entry_type: Meal type — "breakfast", "lunch", "dinner", or "side" (default "dinner")
Inputs: end_date (required), start_date (required), entry_type. Returns: result
get_categoriesA
List all recipe categories.
Inputs: no named parameters. Returns: result
get_cookbook_recipesB
Get recipes in a cookbook.
Args: cookbook_slug: Cookbook slug identifier page: Page number (default 1) per_page: Results per page (default 10)
Inputs: cookbook_slug (required), page, per_page. Returns: result
get_cookbooksA
List all cookbooks.
Inputs: no named parameters. Returns: result
get_meal_plansB
Get meal plan entries for a date range.
Args: start_date: Start date (YYYY-MM-DD) end_date: End date (YYYY-MM-DD)
Inputs: end_date (required), start_date (required). Returns: result
get_recipeA
Get full recipe details including ingredients, instructions, and nutrition.
Args: slug: Recipe slug identifier (from search results)
Inputs: slug (required). Returns: result
get_recipe_ingredientsA
Get just the ingredient list for a recipe.
Args: slug: Recipe slug identifier
Inputs: slug (required). Returns: result
get_shopping_listA
Get a shopping list with all its items.
Args: list_id: Shopping list ID (from get_shopping_lists)
Inputs: list_id (required). Returns: result
get_shopping_listsA
List all shopping lists.
Inputs: no named parameters. Returns: result
get_tagsA
List all recipe tags.
Inputs: no named parameters. Returns: result
get_unitsA
List all measurement units available in Mealie.
Inputs: no named parameters. Returns: result
remove_shopping_list_itemB
Remove an item from a shopping list.
Args: list_id: Shopping list ID (for context) item_id: Item ID to remove (from get_shopping_list)
Inputs: item_id (required), list_id (required). Returns: result
search_foodsC
Search the foods database.
Args: query: Search text page: Page number (default 1) per_page: Results per page (default 10)
Inputs: page, query, per_page. Returns: result
search_recipesA
Search recipes by keyword with optional category/tag filters.
Args: query: Search text (name, description, ingredients) page: Page number (default 1) per_page: Results per page (default 10) categories: Filter by category slugs tags: Filter by tag slugs
Inputs: page, tags, query, per_page, +1 more. Returns: result
update_recipeA
Update fields on an existing recipe. Only provided fields are changed.
Args: slug: Recipe slug to update name: New recipe name description: New description recipe_yield: Yield description (e.g. "15–18 rolls", "1 loaf") servings: Numeric serving count that enables scaling (e.g. 6, 8, 15) total_time: New total time prep_time: New prep time perform_time: New cook time ingredients: Replace ingredient list. Each dict has optional keys: - section (str): creates a visual section header (no other fields used) - quantity (float): numeric amount (e.g. 300, 2.5) - unit (str): unit name or abbreviation (e.g. "g", "cup", "tbsp") - food (str): ingredient name (e.g. "bread flour", "butter") - comment (str): extra info shown alongside (e.g. "softened", "about 1¾ tsp") instructions: Replace instruction steps — each may be a plain string or a dict with: - text (str): step body - title (str, optional): step heading shown in UI - summary (str, optional): one-line takeaway for cook mode - ingredient_refs (list[str], optional): UUIDs of linked ingredients categories: Replace categories tags: Replace tags notes: Replace note blocks. Each dict has: - title (str): section label (e.g. "Non-Negotiables") - text (str): note body extras: Replace arbitrary JSON metadata (e.g. {"isFoundation": true})
Inputs: slug (required), name, tags, notes, +10 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Each tool targets a distinct resource/action pair, and the descriptions clarify boundaries. Minor overlap exists between get_recipe/get_recipe_ingredients and add_recipe_to_shopping_list/add_shopping_list_item, but an agent should be able to disambiguate.
All tools follow a consistent verb_noun pattern in snake_case (get_, create_, delete_, search_, update_, add_, remove_, check_, generate_). Even compound tools like create_recipe_from_url stay within the convention.
27 tools is on the heavy side and above the typical 3-15 range, but the server covers several coherent subdomains: recipes, meal planning, shopping lists, and taxonomy. The count is manageable because almost every tool maps to a distinct operation, though a few convenience tools could be consolidated.
Recipe CRUD, import, search, meal-plan management, and shopping-list item workflows are well covered. Minor gaps remain for updating/deleting categories, tags, and cookbooks, and for updating meal-plan entries or shopping-list items.
Maintenance
Related MCP Connectors
Your Recipes, Beautifully Kept. weReci MCP server lets Claude and other MCP clients work with your personal weReci cookbook, the recipes you've imported from the web, social video and scanned family books. Interactive UI in the chat. weReci supports MCP Apps, so in clients that support it, tools return live views instead of plain text: recipe cards, shopping lists and your recipe graph. Clients without MCP Apps support get the same results as text. Find and read recipes: search your collection in plain language, open any recipe in full, or get an overview of what's in your cookbook. Cook with them: scale a recipe to any serving count, with cooking adjustments as well as amounts. Get substitution suggestions with ratios and caveats. Explore connections: browse your recipe graph (shared ingredients, techniques and cuisines), trace the connection between two recipes, and look up where a dish sits on the cuisine map. Themed collections: list the themed groups weReci curates from your cookbook, or ask it to reshuffle them. Shop: build a shopping list from one or more recipes, add or update items, and read the list back. Share: email a recipe to someone. Longer jobs like conceit reshuffles run in the background, with tools to check their progress. Everything is scoped to your own cookbook, or to a shared one you've joined.
Household meal planning: recipes, weekly meal plans, and grocery lists for your AI agent.
Scraps Kitchen gives any AI agent a persistent, household-aware kitchen memory. Unlike generic chatbot recall, Scraps maintains structured cooking data: what's in your fridge (with freshness tracking), who you cook for (with allergens, dietary restrictions, and preferences), your recipe collection (with cook notes and per-diner ratings), your shopping list, and your kitchen equipment. 27 tools across 6 domains let agents read kitchen context, suggest meals that respect dietary safety, update the pantry after cooking, and build a history of what works for your household. Every interaction makes the data richer. Cooking history, preference signals, kitchen awareness = better suggestions next time. All tools work via oAuth and a free scraps.kitchen account.
Household-aware cooking brain: pantry, meal suggestions, dietary safety, recipes, shopping lists.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for MealMastery AI meal planning that enables users to manage meal plans, recipes, and grocery lists through natural language conversation with AI agents like Claude.52 npmMIT
- AlicenseNot gradedqualityAmaintenanceA MCP server for Mealie recipe management. Exposes 43 tools and 1 prompt for AI assistants to search, create, and manage recipes, meal plans, shopping lists, categories, and tags.140 npm19MIT
- AlicenseNot gradedqualityDmaintenanceConnects MCP clients like Claude to your Mealie recipe manager, enabling natural language search, creation, import, and updates of recipes.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server for Mealie that provides curated tools for recipes, meal plans, and cookbooks with compact responses, enabling natural language management of your Mealie instance.1MIT