mealie-mcp

Un servidor del Model Context Protocol para Mealie, el gestor de recetas y planificador de comidas autoalojado.

Proporciona a un modelo una vista depurada de una instancia de Mealie: buscar y leer recetas con sus ingredientes y pasos, importar nuevas desde un sitio web, mantener organizadas las etiquetas y categorías, planificar comidas, crear listas de la compra a partir de esos planes y registrar lo que realmente se cocinó.

📖 Documentación completa en mealie-mcp.ni-c.de

La API REST de Mealie tiene 259 operaciones distribuidas en 175 rutas. Este servidor expone 52 herramientas, elegidas de modo que las tareas comunes se realicen con una sola llamada y la superficie peligrosa sea inalcanzable. Verificado con Mealie v3.22.0; la fuente de verdad para cada forma de petición es el GET /openapi.json de una instancia en ejecución, no la documentación publicada, que está desactualizada en varios puntos.

Requisitos

• Node.js 22 o superior

• Una instancia de Mealie y un token de API desde Ajustes → Tokens de API

Related MCP server: Blender Open MCP

Configuración

Las dos booleanas se comparan con la cadena literal true, por lo que un error tipográfico las deja desactivadas — verifique la línea de inicio en stderr, que informa el modo en vigor.

El token se elimina del entorno del proceso una vez leído, por lo que los procesos hijo no pueden capturarlo de /proc/<pid>/environ.

Instalación

Claude Desktop, o cualquier cliente MCP que acepte una configuración JSON:

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

O como contenedor:

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

Para probar las herramientas de forma interactiva:

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

Herramientas

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

Importación — preview_recipe_url (prueba en seco, no guarda nada), import_recipe_from_url, import_recipe_from_html_or_json, import_recipe_from_image

Organización — list_organizers, create_organizer, update_organizer, delete_organizer 🔒 — cada uno acepta kind: tag | category | tool

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

Planificación de comidas — list_mealplans, get_todays_meals, create_mealplan_entry, create_random_meal, update_mealplan_entry, delete_mealplan_entry 🔒

Compras — 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

Libros de recetas — list_cookbooks, get_cookbook, create_cookbook, delete_cookbook 🔒

Notas y uso compartido — 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

Instancia — get_about

🔒 necesita un token de confirmación: llame una vez para recibirlo, luego otra vez con él.

Las recetas se pueden direccionar por slug o por UUID en cualquier lugar — Mealie divide su espacio de identificadores entre ambos, y las herramientas resuelven el que reciben.

No expuestas, a propósito

Todo lo que está en /api/admin (copias de seguridad, restauración, mantenimiento, gestión de usuarios, grupos y hogares, correo electrónico, ajustes de proveedor de IA), /api/users/api-tokens (una herramienta que genera credenciales de API es superficie de escalada de privilegios), las rutas de autenticación, CRUD de usuarios y contraseñas, webhooks, notificaciones de eventos y acciones de recetas (todas disparan HTTP saliente desde la instancia), reglas de planificación de comidas, migraciones, sembradores, invitaciones, exportación masiva y descarga ZIP, y carga de activos e imágenes.

Tampoco se expone PUT /api/recipes/{slug}: reemplaza el objeto de receta completo de 33 campos, por lo que una actualización parcial a través de él elimina silenciosamente ingredientes, pasos y etiquetas. update_recipe usa PATCH.

Seguridad

• El contenido de la instancia es entrada no confiable. Las recetas suelen extraerse de sitios web arbitrarios y los comentarios provienen de otros usuarios, por lo que cada resultado de herramienta que pueda contener contenido de la instancia va prefijado con un marcador explícito que indica al modelo que lo trate como datos. Esto importa también después de la importación: el texto permanece en la base de datos y regresa a través de get_recipe.

• Las herramientas de importación hacen que Mealie obtenga la URL, no este servidor. Las URLs están restringidas a direcciones http/https públicas; se rechazan hosts de bucle local, rango privado, enlace local y .lan/.internal/.local.

• Los mensajes de confirmación no citan texto de origen — solo identificadores, conteos y banderas.

• Las respuestas están acotadas: los resultados sobredimensionados descartan elementos completos en lugar de cortar el JSON a medias, y el cuerpo de una respuesta nunca se lee más allá de 8 MB.

• Se rechazan las redirecciones para que el token no pueda reenviarse a otro host.

Consulte SECURITY.md para conocer el modelo de confianza y cómo informar una vulnerabilidad.

Desarrollo

npm install && npm test && npm run build

scripts/verify-live.mjs prueba las 52 herramientas contra una instancia desechable de Mealie; la receta para configurar una está en CONTRIBUTING.md.

El diagrama de arquitectura y la tarjeta social se renderizan desde docs/assets/architecture.source.svg y docs/assets/og.json mediante npm run assets; CI falla si se editó manualmente una copia renderizada.

Publicación de versiones

Todo se maneja mediante una etiqueta; no hay paso de publicación manual.

1. Mueva la sección [Unreleased] de CHANGELOG.md a la nueva versión y póngale fecha. El flujo de trabajo de publicación extrae esa sección con awk, por lo que la forma del encabezado ## [x.y.z] es importante.

2. Actualice version en package.json.

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

4. Confirme, luego una etiqueta firmada y anotada:

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

release.yml verifica entonces que la etiqueta coincida con package.json, publica en npm mediante Trusted Publishing (OIDC — no existe un token npm que pueda filtrarse) con procedencia, sincroniza la versión en ambas entradas del paquete server.json, publica en el registro MCP y crea la versión de GitHub a partir de la sección del changelog. ci.yml envía la imagen de contenedor multiarquitectura a GHCR en paralelo.