mealie-mcp-server

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

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

• 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. See Updating Structured Recipe Ingredients in Workflows.

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

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

• Zero Runtime Dependencies Beyond the SDK — Uses native fetch, no axios or httpx.

Related MCP server: mcp-mealie

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, structured ingredient writes, and the recipe classification feed.

• 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 (53 total)

Recipes (16)

get_recipes, find_recipes_for_ingredients, get_recipe_detailed, get_recipe_concise, get_recipes_batch, get_recipes_detailed_batch, get_recipes_for_classification, create_recipe, patch_recipe, update_recipe_ingredients, update_recipe_taxonomy, update_recipe_taxonomy_batch, duplicate_recipe, mark_recipe_last_made, set_recipe_image_from_url, delete_recipe

Meal Plans (5)

get_all_mealplans, get_mealplan_with_recipes, create_mealplan, create_mealplan_bulk, get_todays_mealplan

Categories (7)

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

Tags (7)

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

Shopping Lists (13)

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

Foods (5)

get_foods, get_food, create_food, update_food, delete_food

License

MIT