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.

Agents

Commands

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

Shopping Lists

Meal Plans

Organizers

Foods & Units

Requirements

• Python 3.11+
• [uv](https://docs.astral.sh/uv/) package manager
• [Mealie](https://mealie.io/) 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