mealie-mcp-server

Ein Model Context Protocol (MCP)-Server für die Rezeptverwaltung mit Mealie. Er stellt 46 Tools und einen Prompt für KI-Assistenten bereit, um Rezepte, Speisepläne, Einkaufslisten, Kategorien und Tags zu suchen, zu erstellen und zu verwalten.

Features

• Rezeptverwaltung – Rezepte suchen, erstellen, patchen, duplizieren und löschen. Mehrere Rezepte mit begrenzter Parallelität im Batch abrufen.

• Zutatenbasierte Rezeptsuche – find_recipes_for_ingredients löst menschenlesbare Zutatennamen (niemals Mealie-Food-UUIDs) gegen die Food-Taxonomie von Mealie auf und findet passende Rezepte über den Mealie-Recipe-Finder. Gibt es keine exakte Food-Übereinstimmung, wird auf die normale Rezeptsuche zurückgegriffen – nützlich für Erkundungen wie „Was kann ich mit X kochen?“, auch für Zutaten, die Mealie unter genau diesem Namen nicht kennt (das aufrufende LLM erweitert die Suche mit Ersatzbegriffen; das MCP rät selbst nie einen Substitut aus).

• Zuweisung von Rezeptkategorien und -Tags – Kategorien und Tags bestehenden Rezepten zuweisen, mit Merge-/Replace-Semantik, Namens-/Slug-/ID-Auflösung und optionaler automatischer Erstellung fehlender Werte, ohne Zutaten, Anleitungen, Nutrition oder andere Rezeptfelder zu verändern. Verfügbar über patch_recipe, update_recipe_taxonomy und update_recipe_taxonomy_batch.

• Speisepläne – Speisepläne anzeigen, erstellen und in großen Mengen erstellen. Das zusammengesetzte Tool ruft Speisepläne mit eingebetteten Rezeptdetails (auch Nährwertangaben) über abbrechene (concurrent) ABCD-Anfragen ab und vermeidet so N+1-Fragen.

• Einkaufslisten – Vollständige CRUD-Operationen für Listen und Artikel, Batch-Operationen und die Integration von Rezepten in Listen.

• Kategorien & Tags – Vollständige CRUD-Operationen zum Organisieren von Rezepten, einschließlich Erkennung leerer Kategorien und Tags.

• Batch- und Composite-Tools – get_recipes_batch und get_recipes_detailed_batch für Rezeptabfragen mit begrenzter Parallelität, get_mealplan_with_recipes für Speisepläne mit eingebetteten Rezeptdaten und clientseitiger Datumsfilterung, update_recipe_taxonomy_batch für gleichzeitige Kategorien-/Tag-Aktualisierungen über viele Rezepte hinweg.

• Keine Laufzeit-Abhängigkeiten (außer dem SDK) – Verwendet nativ fetch, kein axios oder httpx.

Related MCP server: mcp-mealie

Anforderungen

• Node.js >= 22

• Eine laufende Mealie-Instanz mit einem API-Schlüssel

Installation

Schnellstart (npx)

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

opencode-Konfiguration

Füge zu deiner opencode.json hinzu:

{
  "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

Führe den MCP-Server in einem Container aus:

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

Oder mit 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

Lokale Entwicklung

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

Stelle sicher, dass MEALIE_BASE_URL und MEALIE_API_KEY in deiner Umgebung oder in der opencode-Konfiguration gesetzt sind.

Dokumentation

Siehe API Coverage für eine detaillierte Aufschlüsselung aller 46 Tools und der zugehörigen Mealie-API-Endpunkte.

Rezepte nach Zutaten finden

find_recipes_for_ingredients ermöglicht einem KI-Assistenten, Rezepte anhand von menschlich lesbaren Zutatennamen (z. B. "branzino", "chicken thighs") zu finden, ohne die internen Food-UUIDs von Mealie zu kennen. Das MCP übernimmt alle Mealie-spezifischen Abläufe – die Auflösung von Namen in Mealie-Food-Objekte, den Aufruf von Mealie Recipe Finder (GET /api/recipes/suggestions) oder die normale Rezeptsuche – während große Umbewertungen/Erweiterungen (z. B. die Entscheidung, dass "sea bass" oder "whole fish" vernünftige Ersätze für "branzino" sind) dem aufrufenden LLM überlassen werden.

Zutatenauflösung, nacheinander, pro Zutat:

1. Exakte, case-insensitive Übereinstimmung mit dem Namen des Food-Objekts.

2. Exakte, case-insensitive Übereinstimmung mit dem Pluralnamen des Food-Objekts oder einem seiner Aliase (das Mealie-Food-Objekt hat kein slug-Feld, im Gegensatz zu Category/Tag).

3. Ein einziges eindeutiges Ergebnis der Mealie-Food-Suche, wenn oben nichts passt.

Wenn ein Name mehrere Food-Objekte matcht und es keinen eindeutigen Kandidaten gibt (z. B. "fish"), wird er als ambiguous mit den Kandidatennamen zurückgemeldet – das Tool errägt nie.

Suchstrategie, abhängig davon, was aufgelöst wurde:

{ "ingredients": ["salmon"], "categories": ["Dinner"] }

Löst salmon zu einem Food-Objekt auf und ruft dann den Mealie-Recipe-Finder auf. Rezepte werden danach sortiert, wie viele der aufgelösten Zutaten sie verwenden und wie wenige andere Zutaten ihnen fehlen. matchSource: "suggestions".

{ "ingredients": ["branzino"] }

Kein Food-Kandidat für branzino → Rückgriff auf die normale Mealie-Rezeptsuche (sucht in Rezeptname, Beschreibung und Zutatentext). Wenn auch das nichts Nützliches liefert, unresolvedIngredients berichtet es dem LLM, damit es es mit einem breiterenSuchbegriff wie "sea bass" oder "whole fish" erneut versucht. matchSource: "text-search" (oder "none" wenn nichts zurückkam).

{ "ingredients": ["chicken thighs", "broccoli"], "requireAllIngredients": true }

Bei zwei oder mehr aufgelösten Zutaten und requireAllIngredients: true wird die normale Mealie-Rezeptsuche verwendet, mit einem strikten food-basierten UND-Filter statt des Finders. matchSource: "food-filter".

categories/tags werden genauso wie bei get_recipes aufgelöst – nach Name, Slug oder ID, case-insensitive – bevor eine Suche ausgeführt wird, und als einfache IDs an Mealie für die Food-Filter- und Textsuch-Pfade gesendet; für den Recipe-Finder-Pfad (der keine eigenen Taxonomie-Filter hat) werden sie stattdessen auf die zurückgegebenen Kandidaten angewendet.

Jedes zurückgegebene Rezept enthält name, slug, description, categories, tags, totalTime, welche angeforderten Zutaten verwendet wurden und (bei Recipe-Finder-Ergebnissen) welche anderen Zutaten fehlen. Das betrifft genug, um zu entscheiden, ob get_recipe_detailed oder get_recipes_batch sich genauer kennen sollte, ohne einen zusätzlichen Roundtrip pro Kandidat.

Kategorien & Tags zuweisen

Kategorien sind breitereGruppierungen (z. B. Dinner, Dessert), um das Rezeptbuch zu organisieren, während Tags spezifischere, frei formbare Attribute sind (z. B. Quick, Dairy-Free). Beide können über update_recipe_taxonomy (ein Tool, das genau diesen Zweck erfüllt) oder über patch_recipe einem vorhandenen Rezept zugewiesen werden, wobei patch_recipe auch categories/tags/taxonomyMode/createMissing zusätzlich zu den bestehenden Feldern akzeptiert, damit eine Namens-/Beschreibungsänderung und eine Taxonomie-Änderung in einem Aufruf möglich sind.

Jeder Wert in categories/tags kann ein Name, Slug oder eine ID sein. Der Abgleich gegen bestehende Kategorien/Tags erfolgt unabhängig von Groß-/Kleinschreibung bei Name und Slug. Ergebnisse werden automatisch dedupliziert.

Kategorie und einige Tags hinzufügen und den Rest des Rezepts bebehalhalten (mode: "merge", der Standard):

{
  "slug": "chicken-shawarma",
  "categories": ["Dinner"],
  "tags": ["Dairy-Free", "Quick"],
  "mode": "merge",
  "createMissing": false
}

Tag-Liste vollständig ersetzen und bisherige Tags verwerfen:

{
  "slug": "chicken-shawarma",
  "tags": ["Weeknight", "Middle Eastern"],
  "mode": "replace",
  "createMissing": true
}

createMissing: true oben bedeutet, dass Weeknight und Middle Eastern automatisch erstellt werden, falls sie noch nicht existieren.

Alle Kategorien eines Rezepts entfernen, indem ein leeres Array mit mode: "replace" übergeben wird – stattdessen categories weglassen würde die Kategorien unverändert lassen:

{
  "slug": "chicken-shawarma",
  "categories": [],
  "mode": "replace"
}

Viele Rezepte auf einmal aktualisieren mit update_recipe_taxonomy_batch. Jeder Eintrag wird unabhängig verarbeitet (begrenzte Parallelität), und die Antwort enthält ein Erfolg- oder Fehlerergebnis für jedes Rezept, sodass ein einzelner ungültiger Slug nicht die gesamte Batch abbruch.

{
  "updates": [
    { "slug": "chicken-shawarma", "categories": ["Dinner"], "mode": "merge" },
    { "slug": "banana-bread", "tags": ["Dessert", "Baking"], "mode": "merge" },
    { "slug": "does-not-exist", "categories": ["Dinner"], "mode": "merge" }
  ]
}

Beide Tools geben id/slug des Rezepts sowie pro Sammlung die final-Liste nach dem Update, was added, removed oder created wurde – nützlich, um zu prüfen, was genau geändert wurde.

Mitwirken

Dein Beitrag ist willkommen! Babe die Contribution Guidelines, um loszulegen.

Entwicklung

Voraussetzungen

• Node.js >= 22

• Yarn (über Corepack: corepack enable)

• Eine Mealie-Instanz für Integtrationstematische tests (oder Mocke die fetch-Ebene)

Test

yarn test

Typprüfung

yarn typecheck

Build

yarn build

Lint

yarn lint

Verfügbare Tools (46 insgesamt)

Rezepte (14)

get_recipes, find_recipes_for_ingredients, get_recipe_detailed, get_recipe_concise, get_recipes_batch, get_recipes_detailed_batch, create_recipe, patch_recipe, update_recipe_taxonomy, update_recipe_taxonomy_batch, duplicate_recipe, mark_recipe_letzter_made, set_recipe_image_from_url, delete_recipe

Speisepläne (5)

get_all_mealplans, get_mealplan_with_recipes, create_mealplan, create_mealplan_bulk, get_todays_mealplan

Kategorien (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

Einkaufslisten (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

Lizenz

MIT