Skip to main content
Glama

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-recipe

  • Dietary 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

1. Add the Marketplace

/plugin marketplace add https://github.com/thrivewell-partners/mealie-mcp

2. Install the Plugin

/plugin install mealie@thrivewell-marketplace

3. 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" >> .env

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

recipe-creation

"add a recipe", "create a recipe for [dish]", "save this recipe to Mealie"

Structured Mealie v3 recipe authoring with family defaults

foundations

"foundation recipe", "the why behind the how", "educational recipe"

Educational Foundation recipe paradigm with full technique documentation

dietary-management

"check for dietary issues", "substitute the oil", "is this family-friendly"

Compliance checking, pork/seed-oil detection, substitution guidance

cooking-tips

"how do I braise", "homesteading cooking", "what is fond", "how to render tallow"

Scratch cooking techniques with food science explanations

meal-planning

"plan meals for the week", "weekly menu", "what should we eat"

Weekly meal planning via Mealie API

Agents

Agent

Color

Triggers

Role

recipe-advisor

Green

Recipe modification discussions, dietary evaluation, substitution requests

Read-only recipe consultant — evaluates and advises

meal-planner

Blue

"Plan the week's meals", "fill in the meal plan", multi-day meal requests

Drafts weekly menus, gets approval, creates Mealie entries

cooking-teacher

Cyan

"Teach me how to", technique questions, troubleshooting cooking failures

Explains the science and technique behind cooking methods

Commands

Command

Usage

Description

/mealie:quick-recipe

/mealie:quick-recipe [recipe name]

Guided step-by-step recipe creation into Mealie

/mealie:weekly-menu

/mealie:weekly-menu [YYYY-MM-DD]

Plan a week of dinners, get approval, create Mealie entries

/mealie:find-recipe

/mealie:find-recipe [query] [--tag name] [--category name]

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_recipes

Search by keyword with category/tag filters

get_recipe

Full recipe detail including ingredients, instructions, nutrition, notes

get_recipe_ingredients

Ingredient list only

create_recipe_from_url

Import from URL (Mealie scrapes automatically)

create_recipe

Create manually with full structured content

update_recipe

Update any fields on an existing recipe

delete_recipe

Permanently delete a recipe

Shopping Lists

Tool

Description

get_shopping_lists

List all shopping lists

get_shopping_list

View list with all items (checked/unchecked)

create_shopping_list

Create new empty list

delete_shopping_list

Delete a list

add_shopping_list_item

Add item to a list

remove_shopping_list_item

Remove item from a list

check_shopping_list_item

Check or uncheck an item

add_recipe_to_shopping_list

Add all recipe ingredients to a list

Meal Plans

Tool

Description

get_meal_plans

View plans for a date range

create_meal_plan_entry

Add entry (recipe or freeform) for a date

delete_meal_plan_entry

Remove an entry

generate_random_meal_plan

Auto-fill date range with random recipes

Organizers

Tool

Description

get_categories

List all recipe categories

get_tags

List all tags

get_cookbooks

List all cookbooks

get_cookbook_recipes

Recipes in a specific cookbook

create_category

Create a new category

create_tag

Create a new tag

Foods & Units

Tool

Description

search_foods

Search Mealie's foods database

get_units

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 pytest

Project 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 metadata

License

MIT

Available Tools

27 tools
add_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

    A3.6/5.0

    Scored across 27 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    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.

      https://wereci.xyz/api/mcp
    • Household meal planning: recipes, weekly meal plans, and grocery lists for your AI agent.

      https://www.mealplanvault.com/mcp
    • 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.

      https://api.scraps.kitchen/mcp
    • Household-aware cooking brain: pantry, meal suggestions, dietary safety, recipes, shopping lists.

      https://api.scraps.kitchen/mcp

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      A 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 npm
      19
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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.
      1
      MIT