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

---

Installation

As a Claude Code Plugin (Recommended)

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