mealie-mcp-server

Un servidor Model Context Protocol (MCP) para la gestión de recetas de Mealie. Expone 53 herramientas y 1 prompt para que los asistentes de IA busquen, creen y gestionen recetas, planes de comidas, listas de la compra, categorías, etiquetas y alimentos.

Características

• Gestión de recetas — Buscar, crear, modificar, duplicar y eliminar recetas. Obtener múltiples recetas en lote con concurrencia limitada.

• Descubrimiento de recetas por ingrediente — find_recipes_for_ingredients resuelve nombres de ingredientes legibles por humanos (nunca UUIDs de alimentos de Mealie) contra la taxonomía de alimentos de Mealie y encuentra recetas coincidentes mediante el Recipe Finder de Mealie, recurriendo a la búsqueda normal de recetas cuando no hay una coincidencia exacta de alimento — útil para el descubrimiento del tipo "¿qué puedo hacer con X?", incluyendo ingredientes que Mealie no conoce por ese nombre exacto (el LLM que llama amplía la búsqueda con términos sustitutivos; el propio MCP nunca adivina sustituciones). Ver Encontrar recetas por ingrediente en Workflows.

• Asignación de categorías y etiquetas de recetas — Asignar categorías y etiquetas a recetas existentes con semántica de fusión/reemplazo, resolución por nombre/slug/ID y creación automática opcional de valores faltantes, sin alterar ingredientes, instrucciones, nutrición ni ningún otro campo de la receta. Disponible mediante patch_recipe, update_recipe_taxonomy y update_recipe_taxonomy_batch. Ver Asignar categorías y etiquetas en Workflows.

• Planificación de comidas — Ver, crear y crear en lote planes de comidas. La herramienta compuesta obtiene planes de comidas con detalles de recetas incrustados (incluida la nutrición) mediante solicitudes por lotes concurrentes, eliminando las consultas N+1.

• Listas de la compra — CRUD completo para listas y artículos, operaciones en lote e integración de recetas en listas.

• Categorías y etiquetas — CRUD completo para organizar recetas, incluida la detección de categorías/etiquetas vacías.

• Alimentos — CRUD completo para la taxonomía de alimentos (entidades de ingredientes estructurados reutilizables), incluida la gestión de alias y la asignación de etiquetas de alimentos. Ver Resolver o crear un alimento en Workflows.

• Escrituras de ingredientes estructurados — update_recipe_ingredients reemplaza la colección completa de ingredientes estructurados de una receta utilizando referencias de alimentos/unidades ya resueltas, sin alterar ningún otro campo de la receta. Ver Actualizar ingredientes estructurados de recetas en Workflows.

• Herramientas por lotes y compuestas — get_recipes_batch y get_recipes_detailed_batch para la búsqueda de recetas con concurrencia limitada, get_mealplan_with_recipes para planes de comidas con datos de recetas incrustados y filtrado de fechas en el cliente, update_recipe_taxonomy_batch para actualizaciones de categorías/etiquetas con concurrencia limitada en muchas recetas.

• Feed de clasificación de recetas — get_recipes_for_classification es un feed compacto, paginado y de solo lectura diseñado específicamente para la asignación de categorías/etiquetas impulsada por IA. Evita los tiempos de espera que las herramientas por lotes/detalle pueden sufrir en conjuntos de recetas grandes al filtrar con el endpoint de lista económico, obteniendo el detalle completo solo para las coincidencias con la misma búsqueda de concurrencia limitada utilizada anteriormente, y paginando con un cursor estable que sobrevive a ediciones concurrentes de taxonomía. Ver Flujo de trabajo de clasificación de recetas en Workflows.

• Cero dependencias de ejecución más allá del SDK — Utiliza fetch nativo, sin axios ni httpx.

Related MCP server: mcp-mealie

Requisitos

• Node.js >= 22

• Una instancia de Mealie en ejecución con una clave de API

Instalación

Inicio rápido (npx)

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

Configuración de opencode

Añade a tu 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

Ejecuta el servidor MCP en un contenedor:

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

O con 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

Desarrollo local

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

Asegúrate de que MEALIE_BASE_URL y MEALIE_API_KEY estén configuradas en tu entorno o en la configuración de opencode.

Documentación

• Cobertura de API — cada herramienta mapeada a sus endpoints de la API de Mealie subyacentes.

• Flujos de trabajo — guías de uso y ejemplos de cargas útiles para las herramientas más complejas: descubrimiento de ingredientes, asignación de taxonomía, alimentos, escrituras de ingredientes estructurados y el feed de clasificación de recetas.

• Arquitectura — notas de diseño interno para contribuyentes: justificación de la concurrencia limitada, diseño de paginación/cursor y peculiaridades conocidas de la API de Mealie.

Contribuyentes

¡Me encanta tu aportación! Por favor, lee las Directrices de contribución para empezar.

¿Quieres aparecer en la lista de contribuyentes?

Empieza leyendo las Directrices de contribución

Desarrollo

Requisitos

• Node.js >= 22

• Yarn (mediante Corepack: corepack enable)

• Una instancia de Mealie para pruebas de integración (o simular la capa de fetch)

Pruebas

yarn test

Verificación de tipos

yarn typecheck

Compilación

yarn build

Lint

yarn lint

Herramientas disponibles (53 en total)

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

Planes de comidas (5)

get_all_mealplans, get_mealplan_with_recipes, create_mealplan, create_mealplan_bulk, get_todays_mealplan

Categorías (7)

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

Etiquetas (7)

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

Listas de la compra (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

Alimentos (5)

get_foods, get_food, create_food, update_food, delete_food

Licencia

MIT