Mealie

Interactúa con tu base de datos de recetas de Mealie para gestionar y encontrar recetas.

Documentación

Servidor MCP de Mealie

Un servidor de Protocolo de Contexto de Modelo (MCP) que conecta asistentes de IA a tu base de datos de recetas de Mealie a través de clientes como Claude Desktop.

Contenido

Características
Inicio rápido
Configuración
Acceso remoto
Docker
Ejemplos de uso
Herramientas disponibles
Desarrollo
Notas importantes
Soporte y contribuciones
Licencia y créditos

Características

Recetas: Crear, leer, actualizar, importar, duplicar y eliminar recetas.
Búsqueda: Filtrar por texto, categorías, etiquetas y herramientas con lógica Y/O.
Imágenes y archivos: Subir imágenes y archivos de recetas, o establecer imágenes desde URL.
Nutrición y visualización: Establecer nutrición por porción y ajustes de visibilidad de recetas como showAssets y showNutrition.
Ingredientes: Resolver ingredientes de texto libre contra el vocabulario de alimentos y unidades de Mealie.
Listas de compras: Gestionar listas y artículos, realizar operaciones masivas y añadir ingredientes de recetas con escalado de cantidades.
Organización: Gestionar categorías, etiquetas, alimentos, unidades y herramientas de recetas; encontrar categorías y etiquetas no utilizadas.
Planificación de comidas: Ver, crear, actualizar y eliminar entradas de plan de comidas, crear múltiples entradas y marcar recetas como hechas hoy.

Inicio rápido

Requisitos previos

Python 3.12+
Una instancia de Mealie en ejecución y una clave de API desde la configuración de tu cuenta
Gestor de paquetes uv

Instalación

Opción 1: Usando la CLI del SDK de MCP (Recomendado)

Clona el repositorio y luego instala el servidor en Claude Desktop con el comando mcp proporcionado por el SDK de Python de MCP (no se necesita el paquete independiente fastmcp):

git clone https://github.com/rldiao/mealie-mcp-server.git
cd mealie-mcp-server
uv sync --locked
uv run mcp install src/server.py --with-editable . \
  --env-var MEALIE_BASE_URL=https://your-mealie-instance.com \
  --env-var MEALIE_API_KEY=your-mealie-api-key

Opción 2: Usando uvx

Añade esto a la configuración de tu cliente MCP para ejecutarlo directamente desde GitHub sin clonar (en Claude Desktop, usa claude_desktop_config.json):

{
  "mcpServers": {
    "mealie-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rldiao/mealie-mcp-server",
        "mealie-mcp-server"
      ],
      "env": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-mealie-api-key"
      }
    }
  }
}

Reinicia Claude Desktop para cargar el servidor.

Configuración

Establece variables de entorno en la configuración de tu cliente MCP o en el shell. Para una copia local, también puedes copiar .env.template a .env y completar los detalles de tu instancia. Nunca confirmes tu clave de API.

Variable	Predeterminado	Descripción
`MEALIE_BASE_URL`	Obligatorio	URL base de Mealie, incluyendo protocolo y puerto si es necesario
`MEALIE_API_KEY`	Obligatorio	Clave de API desde la configuración de tu cuenta de Mealie
`MEALIE_ENABLE_AI_IMPORT`	`false`	Optar por la importación de recetas con IA; acepta `true`/`false` (sin distinción de mayúsculas)
`MCP_TRANSPORT`	`stdio`	`stdio`, `streamable-http` o el heredado `sse`
`MCP_HOST`	`127.0.0.1`	Dirección de enlace HTTP; usa `0.0.0.0` en contenedores
`MCP_PORT`	`8765`	Puerto HTTP, de 1 a 65535
`LOG_LEVEL`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR` o `CRITICAL`

Acceso remoto

El transporte stdio predeterminado es para clientes locales. Para servir clientes HTTP, configura tus credenciales de Mealie como se describe arriba y ejecuta desde la copia local:

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8765
uv run mealie-mcp-server

El servidor expondrá su endpoint MCP en http://<host>:<port>/mcp.

Seguridad: Los transportes HTTP no tienen autenticación incorporada. Cualquiera que pueda alcanzar el endpoint puede usar las credenciales de Mealie configuradas a través de sus herramientas. Mantenlo en una interfaz de confianza; para acceso remoto, usa un proxy inverso que aplique autenticación y HTTPS.

Docker

El Dockerfile ejecuta el servidor como un contenedor persistente.

Compilar

docker build -t mealie-mcp-server .

Independiente

docker run -d \
  --name mealie-mcp \
  -e MEALIE_BASE_URL=http://your-mealie-host:9000 \
  -e MEALIE_API_KEY=your-mealie-api-key \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8765 \
  -p 127.0.0.1:8765:8765 \
  mealie-mcp-server

El puerto se publica solo en la interfaz de bucle local del host. Consulta Acceso remoto antes de hacerlo accesible remotamente.

Docker Compose

Añade este servicio al archivo Compose que ejecuta Mealie. El ejemplo asume que el servicio de Mealie se llama mealie y ambos servicios usan una red llamada mealie_net, definida en ese archivo Compose. Establece MEALIE_API_KEY en el shell o en el archivo .env de Compose.

services:
  mealie-mcp:
    build: .
    container_name: mealie-mcp
    restart: unless-stopped
    environment:
      MEALIE_BASE_URL: http://mealie:9000
      MEALIE_API_KEY: ${MEALIE_API_KEY}
      MCP_TRANSPORT: streamable-http
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8765"
    expose:
      - "8765"
    networks:
      - mealie_net

expose no publica un puerto del host. Conecta un proxy inverso en la misma red para acceso remoto, siguiendo la guía de seguridad HTTP.

Ejemplos de uso

"Search for chicken recipes"
"Create a new recipe for pasta carbonara"
"Mark the meatloaf recipe as made today"
"Create a shopping list for this week"
"Add all ingredients from the lasagna recipe to my shopping list"
"Plan chicken soup for lunch on Friday"

Consulta Ejemplos de uso para flujos de trabajo detallados y solución de problemas.

Herramientas disponibles

Herramientas de recetas (12 operaciones)

get_recipes - Listar/buscar recetas con filtrado avanzado
get_recipe - Obtener detalles completos de la receta, o un resumen con concise=true
create_recipe - Crear una receta; solo se requiere el nombre, con ingredientes, instrucciones, metadatos, nutrición y ajustes de visualización opcionales
import_recipe_from_url - Importar una receta desde una página web
update_recipe - Actualizar contenido o metadatos, incluyendo nutrición y ajustes de visualización; los campos omitidos se conservan y las listas vacías borran contenido
duplicate_recipe - Clonar una receta
mark_recipe_last_made - Actualizar la marca de tiempo de última preparación
set_recipe_image_from_url - Establecer imagen desde URL
upload_recipe_image_file - Subir archivo de imagen
upload_recipe_asset_file - Subir documento/recurso
update_recipe_categories_and_tags - Reemplazar o borrar categorías, etiquetas o ambas usando IDs
delete_recipe - Eliminar receta

Herramientas de listas de compras (15 operaciones)

get_shopping_lists - Listar todas las listas de compras
create_shopping_list - Crear nueva lista
get_shopping_list - Obtener lista por ID
update_shopping_list - Renombrar una lista conservando otros campos
delete_shopping_list - Eliminar lista
add_recipe_to_shopping_list - Añadir ingredientes de receta
remove_recipe_from_shopping_list - Eliminar ingredientes de receta
get_shopping_list_items - Listar todos los artículos
get_shopping_list_item - Obtener artículo por ID
create_shopping_list_item - Crear artículo individual
create_shopping_list_items_bulk - Crear múltiples artículos
update_shopping_list_item - Actualizar artículo (conserva campos)
update_shopping_list_items_bulk - Actualizar múltiples artículos
delete_shopping_list_item - Eliminar artículo individual
delete_shopping_list_items_bulk - Eliminar múltiples artículos

Herramientas de categorías (6 operaciones)

get_categories - Listar/buscar categorías
get_empty_categories - Encontrar categorías no utilizadas
create_category - Crear nueva categoría
get_category - Obtener por exactamente uno de category_id o category_slug
update_category - Actualizar categoría
delete_category - Eliminar categoría

Herramientas de etiquetas (6 operaciones)

get_tags - Listar/buscar etiquetas
get_empty_tags - Encontrar etiquetas no utilizadas
create_tag - Crear nueva etiqueta
get_tag - Obtener por exactamente uno de tag_id o tag_slug
update_tag - Actualizar etiqueta
delete_tag - Eliminar etiqueta

Herramientas de alimentos (5 operaciones)

get_foods - Listar/buscar alimentos (resolver IDs para ingredientes estructurados)
create_food - Crear un nuevo alimento
get_food - Obtener por ID
update_food - Actualizar alimento
delete_food - Eliminar alimento

Herramientas de unidades (5 operaciones)

get_units - Listar/buscar unidades
create_unit - Crear una nueva unidad
get_unit - Obtener por ID
update_unit - Actualizar unidad
delete_unit - Eliminar unidad

Herramientas de cocina (5 operaciones)

get_tools - Listar/buscar herramientas de recetas (incluye householdsWithTool)
create_tool - Crear una nueva herramienta
get_tool - Obtener por exactamente uno de tool_id o tool_slug
update_tool - Actualizar herramienta
delete_tool - Eliminar herramienta

Herramientas de análisis (1 operación)

parse_ingredients - Resolver una o más líneas de ingredientes en una solicitud; siempre devuelve una lista

Herramientas de plan de comidas (6 operaciones)

get_all_mealplans - Listar planes de comidas
create_mealplan - Crear entrada de plan de comidas
create_mealplan_bulk - Crear múltiples entradas
update_mealplan - Actualizar una entrada conservando campos omitidos
delete_mealplan - Eliminar una entrada
get_todays_mealplan - Obtener las comidas de hoy

Total: 61 herramientas

Con MEALIE_ENABLE_AI_IMPORT=true, import_recipe_with_ai añade una operación de receta opcional: 62 herramientas en total, incluyendo 13 herramientas de recetas. Está ausente del descubrimiento y no se puede llamar cuando está deshabilitada.

Migración de herramientas consolidadas (cambio disruptivo)

Los nombres MCP redundantes se han eliminado, no se conservan como alias. Actualiza la lista de herramientas de tu cliente y actualiza las llamadas guardadas:

Herramienta eliminada	Reemplazo
`create_recipe_full`	`create_recipe` con los mismos argumentos
`get_recipe_detailed`	`get_recipe` (detalles completos por defecto)
`get_recipe_concise`	`get_recipe` con `concise=true`
`patch_recipe`	`update_recipe` con los mismos argumentos
`set_recipe_categories`	`update_recipe_categories_and_tags` con `category_ids`
`set_recipe_tags`	`update_recipe_categories_and_tags` con `tag_ids`
`get_category_by_slug`	`get_category` con `category_slug`
`get_tag_by_slug`	`get_tag` con `tag_slug`
`get_tool_by_slug`	`get_tool` con `tool_slug`
`parse_ingredient`	`parse_ingredients(ingredients=[...])`; lee el primer resultado

Las llamadas existentes de create_recipe y update_recipe siguen siendo compatibles. Las actualizaciones de recetas ahora pueden combinar contenido y metadatos, dejando los campos omitidos o nulos sin cambios. Las listas de ingredientes e instrucciones reemplazan solo los campos proporcionados. La nutrición sigue siendo un reemplazo de objeto completo, mientras que los ajustes se fusionan.

Las operaciones distintas permanecen separadas: las escrituras individuales y masivas tienen contratos de respuesta/fallo diferentes; las listas paginadas difieren de las búsquedas individuales, las consultas de organizador no utilizado y los planes de comidas de hoy. La importación de recetas por URL, el raspado de imágenes por URL y las subidas de archivos también realizan operaciones diferentes.

Importación opcional de recetas con IA

Establece MEALIE_ENABLE_AI_IMPORT=true en el entorno de tu cliente MCP, shell o .env local. Reinicia el servidor y actualiza la lista de herramientas del cliente. Esto se aplica a stdio, SSE y HTTP Streamable. El descubrimiento del SDK sin conexión permanece sin configuración y sin red, listando solo las herramientas predeterminadas; el registro opcional ocurre al inicio del tiempo de ejecución (o al pasar un ServerConfig habilitado explícito).

import_recipe_with_ai requiere Mealie 3.23.0+ y un proveedor de IA predeterminado configurado para el grupo del usuario de la API. Acepta cualquier combinación de:

content: texto plano, HTML sin procesar o JSON; también se usa para correcciones o notas.
url: una URL de receta o video HTTP(S), obtenida por Mealie y guardada como fuente.
image_paths: rutas de imágenes ordenadas accesibles al sistema de archivos del servidor MCP, no a la computadora de un llamador remoto. Múltiples fotos se convierten en una receta; la primera se convierte en su imagen de portada.

Se requiere al menos una fuente no vacía. Las fuentes se combinan, con el contenido pegado teniendo prioridad cuando no coinciden. El translate_language opcional solicita traducción. create_new_organizers predetermina a false: las etiquetas, categorías y herramientas de cocina existentes pueden asignarse, pero las nuevas se crean solo cuando se solicitan explícitamente.

Antes de cada importación, el servidor lee /api/groups/self para verificar aiEnabled y, para fotos, imageProviderEnabled. Las capacidades faltantes o malformadas o una búsqueda fallida producen un error explícito, no un resultado deshabilitado silencioso. La detección de video y el requisito del proveedor de audio son manejados por Mealie. Estas verificaciones establecen configuración, no conectividad del proveedor, credenciales o cuota disponible.

Esta herramienta crea y guarda inmediatamente una receta. El material fuente es procesado por los proveedores de IA configurados de Mealie y puede generar cargos. Revisa la receta devuelta para verificar su precisión. La importación tiene un tiempo de espera de lectura de 300 segundos; otras llamadas a la API conservan sus tiempos de espera existentes. No se reintentan importaciones automáticamente. Después de un tiempo de espera o fallo de conexión, verifica Mealie antes de reintentar o cambiar de herramienta: la creación puede ya haber tenido éxito. Si la búsqueda de seguimiento falla, el error incluye created_slug y stage; recupera esa receta en lugar de importar de nuevo.

Elige la herramienta según la tarea:

Tarea	Herramienta
Página web de recetas ordinaria	`import_recipe_from_url`
Texto no estructurado, fotos, video, fuentes combinadas, traducción o importación explícita con IA	`import_recipe_with_ai` (opt-in)
Guardar ingredientes e instrucciones ya compuestos	`create_recipe`
Adjuntar una foto a una receta existente sin extraer contenido	`upload_recipe_image_file`

El control opt-in solo afecta a esta nueva herramienta. No desactiva el respaldo de IA propio de Mealie para el raspado de URL ni otras funciones de IA existentes. Consulta la documentación de importación con IA de Mealie y los ejemplos de uso.

Desarrollo

Configuración

Después de clonar el repositorio, instala las dependencias de desarrollo:

uv sync --locked --extra dev

Para pruebas manuales, configura tu instancia de Mealie:

cp .env.template .env
# Edit .env with your Mealie instance details

Inicia el MCP Inspector:

uv run mcp dev src/server.py

Ejecuta las comprobaciones sin conexión; estas no requieren una instancia de Mealie ni credenciales:

uv run ruff check src tests
uv run pytest -q

Estructura del Proyecto

Ruta	Propósito
`src/mealie/`	Cliente HTTP y mixins de API
`src/tools/`	Definiciones y registro de herramientas FastMCP
`src/models/`	Modelos de solicitud y respuesta Pydantic
`src/server.py`	Configuración, ciclo de vida y punto de entrada
`src/prompts.py`	Prompts de MCP
`tests/`	Pruebas sin conexión y fixtures

Las convenciones del repositorio están en AGENTS.md, con orientación específica para código fuente y pruebas.

El conjunto automatizado utiliza respuestas HTTP simuladas e incluye comprobaciones de transporte HTTP local. No reemplaza las pruebas de compatibilidad contra tu versión desplegada de Mealie.

Notas Importantes

Las llamadas a continuación utilizan notación estilo Python para ilustrar los argumentos de las herramientas MCP; no son scripts de Python independientes.

Filtrado por Etiquetas y Categorías

Al filtrar recetas, debes usar slugs o UUIDs, no nombres para mostrar:

Usa get_tags() o get_categories() primero para encontrar los slugs correctos:

get_recipes(tags=["quick-meals", "healthy"])

Por ejemplo, pasa quick-meals, no el nombre para mostrar Quick Meals.

La Nutrición se Reemplaza, No se Fusiona

Mealie reemplaza todo el objeto nutrition al escribir. update_recipe hace lo mismo, así que pasa cada valor que quieras conservar:

# Clears every nutrition value except fat.
update_recipe(slug="...", nutrition={"fatContent": "12"})

Análisis de Ingredientes en Lote

Resolver ingredientes manualmente cuesta una o dos llamadas a get_foods / get_units cada uno. parse_ingredients procesa una receta completa en una sola solicitud y devuelve resultados que se pueden pasar directamente a create_recipe:

parse_ingredients(ingredients=["1/4 cup chopped onion", "2 large eggs"])
# -> [{"input": "1/4 cup chopped onion", "confidence": 0.99, "quantity": 0.25,
#      "unit": {"id": "...", "name": "cup"},
#      "food": {"id": "...", "name": "onion"}, "note": "chopped"}, ...]

Una unidad o alimento null significa que tu instancia no tiene una entrada coincidente; créala con create_food / create_unit, o deja el texto en la nota. Pasa verbose=True para la respuesta completa de Mealie, incluidas las confianzas por campo.

Activos Subidos y Nutrición Pueden Almacenarse pero Ocultarse

El objeto settings de una receta controla lo que la interfaz de usuario renderiza. showAssets y showNutrition controlan las tarjetas de activos y nutrición, por lo que un activo subido con upload_recipe_asset_file puede estar presente en la respuesta de la API y aun así ser invisible en la interfaz web. Cambia el interruptor con:

update_recipe(slug="...", settings={"showAssets": True})

Mealie siembra la configuración de una receta nueva a partir de las preferencias del hogar (recipeShowAssets, recipeShowNutrition, ...), por lo que los valores predeterminados difieren según la instancia. Verifica en lugar de asumir.

Solo se cambian los interruptores que pases. La herramienta lee la configuración actual de la receta y envía el objeto fusionado, porque Mealie no conserva de manera confiable los interruptores omitidos en un PATCH de configuración.

Preservación de Campos

Al actualizar elementos de la lista de compras, tanto las actualizaciones individuales como las masivas obtienen los registros actuales y preservan los campos omitidos. Solo necesitas especificar los campos que deseas cambiar:

# Only updates 'checked' field, preserves note, quantity, etc.
update_shopping_list_item(item_id="...", checked=True)

Las entradas de compras masivas aceptan nombres en snake_case como shopping_list_id y los nombres en camelCase de Mealie como shoppingListId. Los alias conflictivos y los IDs duplicados en una actualización masiva se rechazan antes de escribir.

Validación y Limpieza del Plan de Comidas

Las fechas de las comidas deben usar YYYY-MM-DD, y los tipos de entrada deben ser breakfast, lunch, dinner o side. La creación requiere una receta o un título no vacío. Los planes de comidas masivos se validan por completo antes de crear cualquier entrada.

Los campos de actualización omitidos permanecen sin cambios. Para eliminar un enlace de receta existente, usa update_mealplan(entry_id="...", clear_recipe=True, title="Leftovers"). No combines clear_recipe con un recipe_id de reemplazo.

Recuperación de Escrituras Parcialmente Completadas

La creación/población de recetas y la creación masiva de planes de comidas requieren múltiples solicitudes de API y no son atómicas. Si una solicitud posterior falla, el error de la herramienta incluye información de recuperación que identifica el trabajo completado. Inspecciona esa información y el estado actual de Mealie en lugar de reintentar ciegamente toda la operación. Una solicitud fallida o con tiempo de espera agotado puede haberse completado de forma remota.

Soporte y Contribuciones

Consulta el registro de cambios para cambios y notas de migración.
Revisa la guía de uso y la documentación de Mealie.
Reporta problemas a través de problemas de GitHub.
Para solicitudes de extracción, sigue el flujo de trabajo de desarrollo e incluye pruebas para cambios de comportamiento.

Licencia y Créditos

Licenciado bajo la Licencia MIT.

Mealie - El sistema de gestión de recetas
Python MCP SDK - SDK y servidor FastMCP incluido
Model Context Protocol - Documentación del protocolo
Claude Desktop