mealie-mcp-server

Mealie 레시피 관리를 위한 Model Context Protocol (MCP) 서버입니다. AI 어시스턴트가 레시피, 식단 계획, 쇼핑 목록, 카테고리, 태그를 검색하고 생성하며 관리할 수 있도록 46개의 도구와 1개의 프롬프트를 제공합니다.

기능

• 레시피 관리 — 레시피 검색, 생성, 패치, 복제, 삭제. 제한된 동시성으로 여러 레시피를 일괄 가져오기.

• 재료 기반 레시피 검색 — find_recipes_for_ingredients는 사람이 읽을 수 있는 재료 이름(Mealie 음식 UUID가 아님)을 Mealie 음식 분류 체계에 매칭하고 Mealie의 Recipe Finder를 통해 일치하는 레시피를 찾습니다. 정확한 식품 일치 항목이 없을 때 일반 레시피 검색으로 대체되는 등 "X로 무엇을 만들 수 있을까" 스타일의 검색에 유용합니다.

• 레시피 카테고리 및 태그 할당 — 병합/대체 의미 체계, 이름/슬러그/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

• API 키가 있는 Mealie 인스턴스

설치

빠른 시작 (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는 AI 어시스턴트가 사람이 읽을 수 있는 재료 이름(예: "branzino", "chicken thighs")을 Mealie의 음식 분류 체계에 대해 해석하지 않고, Mealie 내부 음식 UUID를 알 필요 없이 사람이 읽을 수 있는 재료 이름을 확인할 수 있습니다. MCP는 모든 Mealie 특정 메커니즘(이름을 Mealie Food 객체로, 별칭, 슬러그, ID, 선택적 자동 생성)을 처리합니다. 재료 대체(예: "sea bass" 또는 "whole fish"가 "branzino"에 적합한지 결정)는 호출 LLM에 남겨집니다.

재료 해석은 각 재료에 대해 순서대로:

1. 식품 이름의 대/소문자 구분 없는 정확히 일치.

2. 식품의 복수형 이름 또는 별칭 중 하나에 대한 정확한 대/소문자 구분 없는 일치 (Category/Tag와 달리 Category/Tag 객체에는 slug 필드가 없음).

3. 위의 항목이 없으면 Mealie의 음식 검색에서 단일 고유 결과.

이름이 여러 음식과 일치하고 고유한 후보가 없으면(예: "fish") ambiguous로 보고되며 후보 이름이 함께 반환됩니다 — 도구는 절대 추측하지 않습니다.

검색 전략은 해결된 내용에 따라 다릅니다:

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

salmon을 Food로 확인한 다음 Mealie의 Recipe Finder를 사용합니다 — 레시피는 확인된 재료를 얼마나 많이 사용하는지, 얼마나 적은 다른 재료가 누락되었는지에 따라 순위가 매겨집니다. 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를 사용하는 경우, Finder 대신 엄격한 식품 기반 AND 필터로 Mealie의 일반 레시피 검색을 사용합니다. matchSource: "food-filter".

categories/tags는 get_recipes와 동일한 방식으로 이름, 슬러그 또는 ID로 대/소문자를 구분하지 않고 확인되며, food-filter 및 text-search 경로에 대한 표준 ID로 Mealie에 전송됩니다. 자체 분류 필터가 없는 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의 모든 값은 이름, 슬러그 또는 ID일 수 있으며, 기존 카테고리/태그와의 일치는 이름과 슬러그에서 대/소문자를 구분하지 않습니다. 결과는 자동으로 중복 제거됩니다.

카테고리와 일부 태그를 추가하고 다른 모든 것은 레시피가 이미 가지고 있는 것으로 유지(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로 한 번에 많은 레시피를 업데이트합니다. 각 항목은 독립적으로 처리되며(제한된 동시성) 응답에는 레시피별 성공 또는 오류 결과가 포함되므로 잘못된 슬러그 하나가 전체 배치를 실패시키지 않습니다:

{
  "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 레이어 모의)

테스트

yarn test

타입 검사

yarn typecheck

빌드

yarn build

린트

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)

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