mealie-mcp-server

Сервер Model Context Protocol (MCP) для управления рецептами в Mealie. Предоставляет ИИ-ассистентам 46 инструментов и 1 промпт для поиска, создания и управления рецептами, планами питания, списками покупок, категориями и тегами.

Возможности

• Управление рецептами — Поиск, создание, изменение, дублирование и удаление рецептов. Пакетное получение нескольких рецептов с ограниченным параллелизмом.

• Поиск рецептов по ингредиентам — find_recipes_for_ingredients сопоставляет читаемые человеком названия ингредиентов (никогда — food UUID в Mealie) с таксономией продуктов Mealie и находит подходящие рецепты через Recipe Finder в Mealie, а при отсутствии точного совпадения по продукту возвращается к обычному поиску рецептов — удобно для поиска вида «что можно приготовить из X», включая ингредиенты, которых Mealie не знает под таким точным названием (вызывающая LLM расширяет поиск словами-заменителями; сам MCP никогда не подбирает замены).

• Назначение категорий и тегов рецептам — Назначайте категории и теги существующим рецептам с семантикой merge/replace, разрешением по имени/slug/ID и опциональным автоматическим созданием недостающих значений, не затрагивая ингредиенты, инструкции, пищевую ценность и любые другие поля рецепта. Доступно через patch_recipe, update_recipe_taxonomy и update_recipe_taxonomy_batch.

• Планирование питания — Просмотр, создание и массовое создание планов питания. Композитный инструмент получает планы питания со встроенными деталями рецептов (включая пищевую ценность) с помощью конкурентных пакетных запросов, что устраняет проблему N+1 запросов.

• Списки покупок — Полный CRUD для списков и позиций, массовые операции и интеграция «рецепт → список».

• Категории и теги — Полный CRUD для организации рецептов, включая обнаружение пустых категорий/тегов.

• Пакетные и композитные инструменты — get_recipes_batch и get_recipes_detailed_batch для поиска рецептов с ограниченным параллелизмом, get_mealplan_with_recipes для планов питания со встроенными данными рецептов и фильтрацией по дате на стороне клиента, update_recipe_taxonomy_batch для обновления категорий/тегов с ограниченным параллелизмом сразу у многих рецептов.

• Ноль зависимостей во время выполнения, кроме SDK — Используется встроенный fetch, без axios или httpx.

Related MCP server: mcp-mealie

Требования

• Node.js >= 22

• Запущенный экземпляр Mealie с API-ключом

Установка

Быстрый старт (npx)

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

Конфигурация opencode

Добавьте в ваш 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

Запустите MCP-сервер в контейнере:

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

Или с помощью 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

Локальная разработка

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

Убедитесь, что MEALIE_BASE_URL и MEALIE_API_KEY заданы в вашем окружении или в конфигурации opencode.

Документация

Подробный разбор всех 46 инструментов и соответствующих им конечных точек Mealie API см. в разделе API Coverage.

Поиск рецептов по ингредиентам

find_recipes_for_ingredients позволяет ИИ-ассистенту находить рецепты по читаемым человеком названиям ингредиентов (например, "branzino", "chicken thighs"), не зная внутренних food UUID в Mealie. MCP берёт на себя всю механику, специфичную для Mealie, — сопоставление названий с объектами Food в Mealie, вызов Recipe Finder в Mealie (GET /api/recipes/suggestions) или обычный поиск рецептов, — а подбор/расширение ингредиентов (например, решение, что «sea bass» или «whole fish» — разумные заменители для «branzino») остаётся на стороне вызывающей LLM.

Разрешение ингредиента, по порядку, для каждого ингредиента:

1. Точное совпадение без учёта регистра по названию продукта.

2. Точное совпадение без учёта регистра по названию продукта во множественном числе или по одному из его псевдонимов (у объекта Food в Mealie нет поля slug, в отличие от Category/Tag).

3. Единственный уникальный результат поиска продуктов в Mealie, если ничего из вышеперечисленного не совпало.

Если название соответствует нескольким продуктам и уникального кандидата нет (например, "fish"), оно возвращается как ambiguous вместе с названиями кандидатов — инструмент никогда не угадывает.

Стратегия поиска в зависимости от того, что удалось сопоставить:

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

Сопоставляет salmon с продуктом Food, затем использует Recipe Finder в Mealie — рецепты ранжируются по тому, сколько из сопоставленных ингредиентов они используют и скольких других ингредиентов им не хватает. matchSource: "suggestions".

{ "ingredients": ["branzino"] }

Для branzino нет совпадения по Food → выполняется откат к обычному поиску рецептов в Mealie (поиск по названию рецепта, описанию и тексту ингредиентов). Если и он не находит ничего полезного, это фиксируется в unresolvedIngredients, чтобы LLM могла повторить попытку с более широким термином, например "sea bass" или "whole fish". matchSource: "text-search" (или "none", если ничего не вернулось).

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

Если сопоставлено два или более ингредиентов и задано requireAllIngredients: true, вместо Recipe Finder используется обычный поиск рецептов в Mealie со строгим AND-фильтром по продуктам. matchSource: "food-filter".

categories/tags сопоставляются так же, как в get_recipes, — по имени, slug или ID без учёта регистра — до запуска любого поиска и передаются в Mealie как канонические ID для путей food-filter и text-search; для пути Recipe Finder (у которого нет собственных фильтров по таксономии) они вместо этого применяются к возвращённым кандидатам.

Каждый возвращённый рецепт включает name, slug, description, categories, tags, totalTime, какие из запрошенных ингредиентов он содержит и (для результатов Recipe Finder) каких других ингредиентов ему не хватает, — этого достаточно, чтобы решить, что стоит изучить подробнее с помощью get_recipe_detailed или get_recipes_batch, без отдельного запроса для каждого кандидата.

Назначение категорий и тегов

Категории — это широкие группировки (например, Dinner, Dessert), используемые для организации книги рецептов, а теги — более конкретные свободные атрибуты (например, Quick, Dairy-Free). И те и другие можно назначить существующему рецепту через update_recipe_taxonomy (специализированный инструмент для этой задачи) или через patch_recipe (который также принимает categories/tags/taxonomyMode/createMissing наряду с существующими полями, так что изменение названия/описания и таксономии можно отправить одним вызовом).

Каждое значение в categories/tags может быть именем, slug или ID — сопоставление с существующими категориями/тегами выполняется без учёта регистра по имени и slug. Результаты автоматически дедуплицируются.

Добавьте категорию и несколько тегов, сохранив всё остальное, что уже есть у рецепта (mode: "merge", по умолчанию):

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

Полностью замените список тегов, отбросив все теги, которые были раньше:

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

Указанный выше createMissing: true означает, что Weeknight и Middle Eastern будут созданы автоматически, если их ещё нет.

Удалите все категории у рецепта, передав явный пустой массив с mode: "replace" — если вместо этого опустить categories, они останутся нетронутыми:

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

Обновите сразу много рецептов с помощью update_recipe_taxonomy_batch. Каждая запись обрабатывается независимо (с ограниченным параллелизмом), и в ответе для каждого рецепта будет результат успеха или ошибки, так что один неверный slug не приведёт к сбою всего пакета:

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

Оба инструмента возвращают id/slug рецепта, а для каждой коллекции — итоговый список final после обновления и то, какие элементы были added, removed или created — удобно, чтобы точно убедиться, что именно изменилось.

Вклад в проект

Буду рад вашему участию! Чтобы начать, ознакомьтесь с Руководством по участию.

Разработка

Требования

• Node.js >= 22

• Yarn (через Corepack: corepack enable)

• Экземпляр Mealie для интеграционного тестирования (или мокайте слой fetch)

Test

yarn test

Typecheck

yarn typecheck

Build

yarn build

Lint

yarn lint

Доступные инструменты (всего 46)

Рецепты (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_last_made, set_recipe_image_from_url, delete_recipe

Планы питания (5)

get_all_mealplans, get_mealplan_with_recipes, create_mealplan, create_mealplan_bulk, get_todays_mealplan

Категории (7)

Категории (7)

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

Теги (7)

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

Списки покупок (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

Лицензия

MIT