mealie-mcp

Ein Model Context Protocol-Server für Mealie, den selbst gehosteten Rezeptverwalter und Speiseplaner.

Er bietet einem Modell eine kuratierte Ansicht einer Mealie-Instanz: Rezepte mit ihren Zutaten und Schritten suchen und lesen, neue von einer Website importieren, Tags und Kategorien ordentlich halten, Mahlzeiten planen, Einkaufslisten aus diesen Plänen erstellen und aufzeichnen, was tatsächlich gekocht wurde.

📖 Vollständige Dokumentation auf mealie-mcp.ni-c.de

Die REST-API von Mealie umfasst 259 Operationen auf 175 Pfaden. Dieser Server stellt 52 Werkzeuge zur Verfügung, die so ausgewählt sind, dass die häufigsten Aufgaben mit einem Aufruf erledigt werden können und die gefährliche Oberfläche gar nicht erst erreichbar ist. Verifiziert gegen Mealie v3.22.0; die maßgebliche Quelle für jede Anfrageform ist das GET /openapi.json einer laufenden Instanz, nicht die veröffentlichte Dokumentation, die an mehreren Stellen veraltet ist.

Anforderungen

• Node.js 22 oder neuer

• Eine Mealie-Instanz und ein API-Token aus Einstellungen → API-Tokens

Related MCP server: Blender Open MCP

Konfiguration

Die beiden Booleschen Werte werden mit dem Literal-String true verglichen, sodass ein Tippfehler sie aus lässt – überprüfen Sie die Startzeile auf stderr, die den tatsächlich aktiven Modus meldet.

Das Token wird aus der Prozessumgebung entfernt, sobald es gelesen wurde, sodass Kindprozesse es nicht aus /proc/<pid>/environ auslesen können.

Installation

Claude Desktop oder ein anderer MCP-Client, der eine JSON-Konfiguration akzeptiert:

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": {
        "MEALIE_URL": "https://mealie.example.com",
        "MEALIE_API_TOKEN": "…"
      }
    }
  }
}

claude mcp add mealie \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  -- npx -y @ni-c/mealie-mcp

Codex (~/.codex/config.toml):

[mcp_servers.mealie]
command = "npx"
args = ["-y", "@ni-c/mealie-mcp"]

[mcp_servers.mealie.env]
MEALIE_URL = "https://mealie.example.com"
MEALIE_API_TOKEN = "…"

Oder als Container:

docker run --rm -i \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  ghcr.io/ni-c/mealie-mcp

Um interaktiv mit den Werkzeugen zu experimentieren:

npx @modelcontextprotocol/inspector npx -y @ni-c/mealie-mcp

Werkzeuge

Rezepte — search_recipes, get_recipe, suggest_recipes, create_recipe, update_recipe, duplicate_recipe, set_recipe_last_made, delete_recipe 🔒

Import — preview_recipe_url (Probelauf, speichert nichts), import_recipe_from_url, import_recipe_from_html_or_json, import_recipe_from_image

Organisieren — list_organizers, create_organizer, update_organizer, delete_organizer 🔒 — jedes erwartet kind: tag | category | tool

Zutaten — list_foods, create_food, merge_foods 🔒, list_units, create_unit, merge_units 🔒, parse_ingredients

Speisepläne — list_mealplans, get_todays_meals, create_mealplan_entry, create_random_meal, update_mealplan_entry, delete_mealplan_entry 🔒

Einkaufen — list_shopping_lists, get_shopping_list, create_shopping_list, delete_shopping_list 🔒, add_shopping_list_items, update_shopping_list_items, delete_shopping_list_items 🔒, add_recipe_to_shopping_list, remove_recipe_from_shopping_list

Kochbücher — list_cookbooks, get_cookbook, create_cookbook, delete_cookbook 🔒

Notizen und Teilen — set_recipe_rating, add_recipe_comment, delete_recipe_comment 🔒, list_recipe_comments, list_recipe_timeline, create_timeline_event, list_share_tokens, create_share_token 🔒, delete_share_token

Instanz — get_about

🔒 benötigt ein Bestätigungstoken: einmal aufrufen, um eines zu erhalten, dann erneut mit diesem.

Rezepte können überall per Slug oder UUID angesprochen werden – Mealie teilt seinen Identifikatorraum zwischen beiden auf, und die Werkzeuge lösen auf, was ihnen übergeben wird.

Absichtlich nicht bereitgestellt

Alles unter /api/admin (Backups, Wiederherstellung, Wartung, Benutzer-, Gruppen- und Haushaltsverwaltung, E-Mail, KI-Anbietereinstellungen), /api/users/api-tokens (ein Werkzeug, das API-Anmeldedaten ausstellt, ist eine Privilegienausweitungs-Oberfläche), die Authentifizierungsrouten, Benutzer-CRUD und Passwörter, Webhooks, Ereignisbenachrichtigungen und Rezeptaktionen (alle drei lösen ausgehende HTTP-Anfragen von der Instanz aus), Speiseplanregeln, Migrationen, Seeders, Einladungen, Bulk-Export und ZIP-Download sowie Asset- und Bild-Uploads.

PUT /api/recipes/{slug} wird ebenfalls nicht bereitgestellt: Es ersetzt das gesamte 33-Felder-Rezeptobjekt, sodass eine partielle Aktualisierung darüber stillschweigend Zutaten, Schritte und Tags verwirft. update_recipe verwendet PATCH.

Sicherheit

• Instanzinhalte sind unvertrauenswürdige Eingaben. Rezepte werden routinemäßig von beliebigen Websites gescrapt, und Kommentare stammen von anderen Benutzern. Daher wird jedem Werkzeugergebnis, das Instanzinhalte enthalten kann, ein expliziter Marker vorangestellt, der dem Modell mitteilt, es als Daten zu behandeln. Dies ist auch nach dem Import wichtig: Der Text bleibt in der Datenbank und wird über get_recipe zurückgeliefert.

• Die Importwerkzeuge lassen Mealie abrufen, nicht diesen Server. URLs sind auf öffentliche http/https-Adressen beschränkt; Loopback-, Private-Range-, Link-Local- und .lan/.internal/.local-Hosts werden abgelehnt.

• Bestätigungsaufforderungen zitieren keine Daten aus der Instanz – nur IDs, Anzahlen und Flags.

• Antworten sind begrenzt: Übermäßig große Ergebnisse werfen ganze Elemente weg, anstatt das JSON mitten im String abzuschneiden, und ein Antworttext wird niemals über 8 MB hinaus gelesen.

• Weiterleitungen werden abgelehnt, damit das Token nicht an einen anderen Host gesendet werden kann.

Siehe SECURITY.md für das Vertrauensmodell und wie Sie eine Sicherheitslücke melden können.

Entwicklung

npm install && npm test && npm run build

scripts/verify-live.mjs testet alle 52 Werkzeuge gegen eine Wegwerf-Mealie-Instanz; die Anleitung zum Einrichten einer solchen finden Sie in CONTRIBUTING.md.

Das Architekturdiagramm und die Social Card werden aus docs/assets/architecture.source.svg und docs/assets/og.json mittels npm run assets gerendert; CI schlägt fehl, wenn eine gerenderte Kopie von Hand bearbeitet wurde.

Veröffentlichung

Alles wird durch einen Tag gesteuert; es gibt keinen manuellen Veröffentlichungsschritt.

1. Verschieben Sie den Abschnitt [Unreleased] der CHANGELOG.md in die neue Version und datieren Sie ihn. Der Release-Workflow extrahiert diesen Abschnitt mit awk, daher ist die Form der ## [x.y.z]-Überschrift wichtig.

2. Erhöhen Sie die version in package.json.

3. npm run lint && npm run build && npm run test:coverage.

4. Committen, dann einen signierten annotierten Tag:

git tag -s v0.1.1 -m "v0.1.1"
git push origin main v0.1.1

release.yml überprüft dann, ob der Tag mit package.json übereinstimmt, veröffentlicht auf npm über Trusted Publishing (OIDC – es existiert kein npm-Token, das preisgegeben werden könnte) mit Provenienz, synchronisiert die Version in beide server.json-Paketeinträge, veröffentlicht im MCP-Register und erstellt die GitHub-Version aus dem Changelog-Abschnitt. ci.yml pusht das Multi-Arch-Container-Image parallel dazu zu GHCR.