mealie-mcp-server

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

기능

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

• 재료 기반 레시피 탐색 — find_recipes_for_ingredients는 사람이 읽을 수 있는 재료 이름(Mealie 식품 UUID가 아님)을 Mealie의 식품 분류 체계에 매핑하고, Mealie의 Recipe Finder를 통해 일치하는 레시피를 찾습니다. 정확한 식품 일치가 없을 때는 일반 레시피 검색으로 대체합니다. "X로 무엇을 만들 수 있을까" 스타일의 탐색에 유용하며, Mealie가 해당 이름으로 정확히 알지 못하는 재료도 포함합니다(호출하는 LLM이 대체 용어로 검색 범위를 넓히며, MCP 자체는 대체를 추측하지 않습니다). 워크플로의 재료로 레시피 찾기를 참조하세요.

• 레시피 카테고리 및 태그 할당 — 병합/교체 의미론, 이름/슬러그/ID 해석, 누락된 값의 자동 생성 옵션을 사용하여 기존 레시피에 카테고리와 태그를 할당합니다. 재료, 조리법, 영양 정보 또는 다른 레시피 필드는 건드리지 않습니다. patch_recipe, update_recipe_taxonomy, update_recipe_taxonomy_batch를 통해 사용할 수 있습니다. 워크플로의 카테고리 및 태그 할당을 참조하세요.

• 식사 계획 — 식사 계획 보기, 생성, 대량 생성. 복합 도구는 동시 배치 요청을 사용하여 영양 정보를 포함한 레시피 세부 정보가 포함된 식사 계획을 가져와 N+1 쿼리를 제거합니다.

• 쇼핑 목록 — 목록 및 항목에 대한 전체 CRUD, 대량 작업, 레시피-목록 통합.

• 카테고리 및 태그 — 레시피 구성을 위한 전체 CRUD, 빈 카테고리/태그 감지 포함.

• 식품 — 식품 분류 체계(재사용 가능한 구조화된 재료 엔티티)에 대한 전체 CRUD, 별칭 관리 및 식품 라벨 할당 포함. 워크플로의 식품 해석 또는 생성을 참조하세요.

• 구조화된 재료 쓰기 — update_recipe_ingredients는 이미 해석된 식품/단위 참조를 사용하여 레시피의 전체 구조화된 재료 컬렉션을 교체하며, 다른 레시피 필드는 건드리지 않습니다. 워크플로의 구조화된 레시피 재료 업데이트를 참조하세요.

• 배치 및 복합 도구 — 제한된 동시성 레시피 조회를 위한 get_recipes_batch 및 get_recipes_detailed_batch, 레시피 데이터가 포함된 식사 계획 및 클라이언트 측 날짜 필터링을 위한 get_mealplan_with_recipes, 여러 레시피에 대한 제한된 동시성 카테고리/태그 업데이트를 위한 update_recipe_taxonomy_batch.

• 레시피 분류 피드 — get_recipes_for_classification은 AI 기반 카테고리/태그 할당을 위해 특별히 설계된 간결하고 페이지네이션된 읽기 전용 피드입니다. 저렴한 목록 엔드포인트로 필터링하고, 위에서 사용한 것과 동일한 제한된 동시성 가져오기로 일치하는 항목에 대해서만 전체 세부 정보를 가져오며, 동시 분류 편집에도 안정적인 커서로 페이지네이션하여 대규모 레시피 세트에서 배치/세부 도구가 겪을 수 있는 시간 초과를 피합니다. 워크플로의 레시피 분류 워크플로를 참조하세요.

• 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

환경 또는 opencode 설정에 MEALIE_BASE_URL 및 MEALIE_API_KEY가 설정되어 있는지 확인하세요.

문서

• API 커버리지 — 모든 도구를 기본 Mealie API 엔드포인트에 매핑.

• 워크플로 — 재료 탐색, 분류 체계 할당, 식품, 구조화된 재료 쓰기, 레시피 분류 피드 등 복잡한 도구에 대한 사용 가이드 및 예제 페이로드.

• 아키텍처 — 기여자를 위한 내부 설계 노트: 제한된 동시성 근거, 페이지네이션/커서 설계, 알려진 Mealie API 특이점.

기여자

여러분의 의견을 환영합니다! 시작하려면 기여 가이드라인을 읽어주세요.

기여자 목록에 등장하고 싶으신가요?

기여 가이드라인을 읽고 시작하세요.

개발

요구 사항

• Node.js >= 22

• Yarn (Corepack 사용: corepack enable)

• 통합 테스트를 위한 Mealie 인스턴스 (또는 fetch 레이어 모킹)

테스트

yarn test

타입체크

yarn typecheck

빌드

yarn build

린트

yarn lint

사용 가능한 도구 (총 53개)

레시피 (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

식사 계획 (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

식품 (5)

get_foods, get_food, create_food, update_food, delete_food

라이선스

MIT