mealie-mcp-server

A Model Context Protocol (MCP) server for Mealie recipe management. Exposes 71 tools and 1 prompt for AI assistants to search, create, and manage recipes, meal plans, shopping lists, categories, tags, foods, units, and tools.

Features

• Recipe Management — Search, create, patch, duplicate, and delete recipes. Batch-fetch multiple recipes with bounded concurrency.
• Ingredient-Based Recipe Discovery — find_recipes_for_ingredients resolves human-readable ingredient names (never Mealie food UUIDs) against Mealie's food taxonomy and finds matching recipes via Mealie's Recipe Finder, falling back to normal recipe search when there's no exact food match — useful for "what can I make with X" style discovery, including ingredients Mealie doesn't know by that exact name (the calling LLM broadens the search with substitute terms; the MCP itself never guesses substitutions). See Finding Recipes by Ingredient in Workflows.
• Recipe Categories & Tags Assignment — Assign Categories and Tags to existing recipes with merge/replace semantics or explicit add/remove deltas, name/slug/ID resolution, and optional auto-creation of missing values, without disturbing ingredients, instructions, nutrition, or any other recipe field. Available via patch_recipe, update_recipe_taxonomy, and update_recipe_taxonomy_batch. See Assigning Categories & Tags in Workflows.
• Meal Planning — View, create, and bulk-create meal plans. Composite tool fetches meal plans with embedded recipe details (including nutrition) using concurrent batch requests, eliminating N+1 queries.
• Shopping Lists — Full CRUD for lists and items, bulk operations, and recipe-to-list integration.
• Categories & Tags — Full CRUD for organizing recipes, including empty-category/tag detection.
• Foods — Full CRUD for the food taxonomy (reusable structured ingredient entities), including alias management and food-label assignment. See Resolving or Creating a Food in Workflows.
• Units — Full CRUD for the ingredient unit vocabulary (e.g. "tablespoon", "cup", "gram"), including alias/abbreviation management and standard-quantity conversion metadata. See Resolving or Creating a Unit in Workflows.
• Batch Food/Unit Candidate Matching — get_food_matches/get_unit_matches resolve many already-interpreted food/unit concepts to candidate Mealie entities (including alias matches that plain get_foods/get_units search misses) in a small, bounded number of requests instead of one search per concept — read-only, and never picks a winner for the caller. See Resolving Several Foods or Units at Once in Workflows.
• Structured Ingredient Writes — update_recipe_ingredients replaces a recipe's complete structured ingredient collection using already-resolved food/unit references, without disturbing any other recipe field, or edits rows incrementally by stable referenceId (add/update/remove, with section titles). Every write is verified against the recipe Mealie returns, and rolled back with a failure report if a requested food/unit association didn't survive persistence — see Post-Write Ingredient Verification. update_recipe_ingredients_batch runs the same write (with the same verification/rollback) across up to 25 recipes at once with bounded concurrency and per-recipe failure isolation, once food/unit resolution is done and per-recipe writes are the remaining bottleneck. See Updating Structured Recipe Ingredients in Workflows.
• Guarded Instruction Updates — update_recipe_instructions (and _batch) edit instruction text/title/summary and instruction-to-ingredient links by snapshot index, guarded by the recipe's updatedAt, with no-op suppression, canonical verification, and rollback. Mealie's regenerated instruction IDs are never used as identity. See Updating Recipe Instructions.
• Batch & Composite Tools — get_recipes_batch and get_recipes_detailed_batch for bounded-concurrency recipe lookup, get_mealplan_with_recipes for meal plans with embedded recipe data and client-side date filtering, update_recipe_taxonomy_batch for bounded-concurrency category/tag updates across many recipes, update_recipe_ingredients_batch for bounded-concurrency structured-ingredient writes across many recipes.
• Recipe Classification Feed — get_recipes_for_classification is a compact, paginated, read-only feed purpose-built for AI-driven Category/Tag assignment. It avoids the timeouts that batch/detail tools can hit on large recipe sets by filtering with the cheap list endpoint, fetching full detail only for matches with the same bounded-concurrency fetch used above, and paginating with a stable cursor that survives concurrent taxonomy edits. See Recipe Classification Workflow in Workflows.
• Ingredient Parsing Work Queue — get_recipes_for_ingredient_parsing is a compact, paginated, read-only feed of recipes whose ingredients may still need structured parsing. It never parses ingredient text itself — it reports each ingredient's existing structured state (a deterministic parsingState: section/unparsed/partial/structured) so the calling LLM can interpret free-form text, resolve foods/units separately, and write the result back with update_recipe_ingredients. See Ingredient Parsing Workflow in Workflows.
• Holistic Data Enrichment Queue — get_recipes_for_data_enrichment is a read-only, paginated queue of recipes matching deterministic enrichment-review filters (ingredient parsing, ingredient sections, instruction-ingredient links, Tools, Categories, Tags, image), combined with match: "any" | "all". Matches are review signals, not verdicts; changes go through the focused write tools. See Recipe Data Enrichment Workflow.
• Server-Level Cross-Tool Guidance — The server publishes MCP instructions (sent to every client at connect time) covering behavior that spans several tools: short general operating principles (reuse canonical entities, prefer batch tools, treat the user's request as authoritative), recipe creation/import orchestration (extracting a complete recipe from a URL, pasted text, an image, a document, or a description), and the detailed ingredient parsing/structuring policy — splitting, alternatives, compound quantities, and referenceId/originalText provenance. Each section is scoped to activate only when the request actually matches it. See Server Instructions in Workflows.
• Zero Runtime Dependencies Beyond the SDK — Uses native fetch, no axios or httpx.

Requirements

• Node.js >= 22
• A running Mealie instance with an API key

Installation

Quick start (npx)

MEALIE_BASE_URL=https://your-mealie-instance.com \
MEALIE_API_KEY=your-api-key \
npx mealie-mcp-server

opencode config

Add to your opencode.json:

{
  "mcp": {
    "mealie-mcp-server": {
      "type": "local",
      "command": ["npx", "mealie-mcp-server"],
      "enabled": true,
      "environment": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-api-key"
      }
    }
  }
}

Docker

Run the MCP server in a container:

docker run -d \
  --name mealie-mcp-server \
  -e MEALIE_BASE_URL=https://your-mealie-instance.com \
  -e MEALIE_API_KEY=your-api-key \
  ghcr.io/timo-reymann/mealie-mcp-server:main

Or with Docker Compose:

version: '3.8'
services:
  mealie-mcp-server:
    image: ghcr.io/timo-reymann/mealie-mcp-server:main
    environment:
      MEALIE_BASE_URL: https://your-mealie-instance.com
      MEALIE_API_KEY: your-api-key
    restart: unless-stopped

Local development

git clone https://github.com/timo-reymann/mealie-mcp-server.git
cd mealie-mcp-server
corepack enable
yarn install
cp .env.template .env
# Edit .env with your MEALIE_BASE_URL and MEALIE_API_KEY
yarn dev

Make sure MEALIE_BASE_URL and MEALIE_API_KEY are set in your environment or opencode config.

Documentation

• API Coverage — every tool mapped to its underlying Mealie API endpoint(s).
• Workflows — usage guides and example payloads for the more involved tools: ingredient discovery, taxonomy assignment, foods, units, structured ingredient writes, the recipe classification feed, and the server-level ingredient parsing instructions published to every connected client.
• Architecture — internal design notes for contributors: bounded-concurrency rationale, pagination/cursor design, and known Mealie API quirks.

Contributors

I love your input! Please read the Contribution Guidelines to get started.

Want to appear in the list of contributors?

Get started by reading the Contribution Guidelines

Development

Requirements

• Node.js >= 22
• Yarn (via Corepack: corepack enable)
• A Mealie instance for integration testing (or mock the fetch layer)

Test

yarn test

Typecheck

yarn typecheck

Build

yarn build

Lint

yarn lint

Available Tools (78 total)

Recipes (26)

create_recipe, delete_recipe, duplicate_recipe, find_recipes_for_ingredients, get_recipe_concise, get_recipe_detailed, get_recipes, get_recipes_batch, get_recipes_detailed_batch, get_recipes_for_classification, get_recipes_for_data_enrichment, get_recipes_for_ingredient_parsing, mark_recipe_last_made, patch_recipe, set_recipe_image, set_recipe_image_from_file, set_recipe_image_from_url, set_recipe_rating, update_recipe_ingredients, update_recipe_ingredients_batch, update_recipe_instructions, update_recipe_instructions_batch, update_recipe_taxonomy, update_recipe_taxonomy_batch, update_recipe_tools, update_recipe_tools_batch

Meal Plans (6)

create_mealplan, create_mealplan_bulk, get_all_mealplans, get_mealplan_with_recipes, get_todays_mealplan, patch_mealplan

Categories (7)

create_category, delete_category, get_categories, get_category, get_category_by_slug, get_empty_categories, update_category

Tags (7)

create_tag, delete_tag, get_empty_tags, get_tag, get_tag_by_slug, get_tags, update_tag

Shopping Lists (13)

add_recipe_to_shopping_list, create_shopping_list, create_shopping_list_item, create_shopping_list_items_bulk, delete_shopping_list, delete_shopping_list_item, delete_shopping_list_items_bulk, get_shopping_list, get_shopping_list_items, get_shopping_lists, remove_recipe_from_shopping_list, update_shopping_list, update_shopping_list_item

Foods (7)

create_food, delete_food, get_food, get_food_matches, get_foods, merge_foods, update_food

Units (6)

create_unit, delete_unit, get_unit, get_unit_matches, get_units, update_unit

Tools (6)

create_tool, delete_tool, get_tool, get_tool_matches, get_tools, update_tool

Prompts (1)

• weekly-meal-plan — Generate a balanced weekly meal plan with breakfast, lunch, and dinner for 7 days

License

MIT