mealie-mcp

Сервер Model Context Protocol для Mealie, саморазмещаемого менеджера рецептов и планировщика питания.

Он предоставляет модели курируемый обзор экземпляра Mealie: поиск и чтение рецептов с их ингредиентами и шагами, импорт новых с веб-сайта, поддержание порядка в тегах и категориях, планирование приёмов пищи, составление списков покупок на основе этих планов и запись того, что было приготовлено на самом деле.

📖 Полная документация на mealie-mcp.ni-c.de

REST API Mealie имеет 259 операций на 175 путях. Этот сервер предоставляет 52 инструмента, выбранных так, чтобы типовые задачи решались одним вызовом, а опасная поверхность была недоступна. Проверено на Mealie v3.22.0; источником истины для каждой формы запроса является GET /openapi.json работающего экземпляра, а не опубликованная документация, которая в нескольких местах устарела.

Требования

• Node.js 22 или новее

• Экземпляр Mealie и токен API из Настройки → Токены API

Related MCP server: Blender Open MCP

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

Два булевых значения сравниваются с литеральной строкой true, поэтому опечатка оставляет их выключенными — проверьте строку запуска в stderr, которая сообщает о действующем режиме.

Токен удаляется из окружения процесса после чтения, поэтому дочерние процессы не могут получить его из /proc/<pid>/environ.

Установка

Claude Desktop или любой MCP-клиент, принимающий 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 = "…"

Или как контейнер:

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

Чтобы интерактивно опробовать инструменты:

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

Инструменты

Рецепты — search_recipes, get_recipe, suggest_recipes, create_recipe, update_recipe, duplicate_recipe, set_recipe_last_made, delete_recipe 🔒

Импорт — preview_recipe_url (пробный запуск, ничего не сохраняет), import_recipe_from_url, import_recipe_from_html_or_json, import_recipe_from_image

Организация — list_organizers, create_organizer, update_organizer, delete_organizer 🔒 — каждый принимает kind: tag | category | tool

Ингредиенты — list_foods, create_food, merge_foods 🔒, list_units, create_unit, merge_units 🔒, parse_ingredients

Планы питания — list_mealplans, get_todays_meals, create_mealplan_entry, create_random_meal, update_mealplan_entry, delete_mealplan_entry 🔒

Покупки — 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

Кулинарные книги — list_cookbooks, get_cookbook, create_cookbook, delete_cookbook 🔒

Заметки и обмен — 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

Экземпляр — get_about

🔒 требует токен подтверждения: вызовите один раз, чтобы получить его, затем снова с ним.

Рецепты можно везде указывать по slug или UUID — Mealie разделяет своё пространство идентификаторов между ними, и инструменты разрешают то, что им передано.

Не предоставлено намеренно

Всё в /api/admin (резервные копии, восстановление, обслуживание, управление пользователями, группами и домохозяйствами, электронная почта, настройки AI-провайдера), /api/users/api-tokens (инструмент, создающий учётные данные API, является поверхностью для повышения привилегий), маршруты аутентификации, CRUD пользователей и пароли, вебхуки, уведомления о событиях и действия с рецептами (все три инициируют исходящий HTTP из экземпляра), правила планов питания, миграции, сидеры, приглашения, массовый экспорт и ZIP-загрузка, а также загрузка ресурсов и изображений.

PUT /api/recipes/{slug} также не предоставлен: он заменяет весь объект рецепта из 33 полей, поэтому частичное обновление через него молча удаляет ингредиенты, шаги и теги. update_recipe использует PATCH.

Безопасность

• Содержимое экземпляра — это недоверенный ввод. Рецепты регулярно извлекаются с произвольных веб-сайтов, а комментарии поступают от других пользователей, поэтому каждый результат инструмента, который может содержать содержимое экземпляра, предваряется явным маркером, сообщающим модели обрабатывать его как данные. Это важно и после импорта: текст остаётся в базе данных и возвращается через get_recipe.

• Инструменты импорта заставляют Mealie выполнять запросы, а не этот сервер. URL-адреса ограничены публичными адресами http/https; адреса loopback, частного диапазона, link-local и .lan/.internal/.local отклоняются.

• Запросы подтверждения не цитируют данные из вышестоящего источника — только идентификаторы, количества и флаги.

• Ответы ограничены: слишком большие результаты отбрасывают целые элементы, а не обрезают JSON посередине строки, и тело ответа никогда не читается более 8 МБ.

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

См. SECURITY.md для описания модели доверия и способов сообщения об уязвимости.

Разработка

npm install && npm test && npm run build

scripts/verify-live.mjs проверяет все 52 инструмента на одноразовом экземпляре Mealie; рецепт его настройки приведён в CONTRIBUTING.md.

Диаграмма архитектуры и социальная карточка генерируются из docs/assets/architecture.source.svg и docs/assets/og.json с помощью npm run assets; CI завершается ошибкой, если отрендеренная копия была отредактирована вручную.

Релиз

Всё управляется тегом; ручного шага публикации нет.

1. Перенесите раздел [Unreleased] из CHANGELOG.md в новую версию и укажите дату. Рабочий процесс релиза извлекает этот раздел с помощью awk, поэтому форма заголовка ## [x.y.z] важна.

2. Обновите version в package.json.

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

4. Зафиксируйте изменения, затем подписанный аннотированный тег:

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

Затем release.yml проверяет, что тег соответствует package.json, публикует в npm через Trusted Publishing (OIDC — нет токена npm, который мог бы быть скомпрометирован) с подтверждением происхождения, синхронизирует версию в обе записи пакета server.json, публикует в реестр MCP и создаёт релиз GitHub из раздела журнала изменений. ci.yml параллельно отправляет многоплатформенный образ контейнера в GHCR.

Лицензия

MIT