Mealie MCP 서버

Mealie를 위한 커뮤니티용 Model Context Protocol (MCP) 서버입니다.

이 서버는 스트리밍 가능한 HTTP 또는 stdio를 통해 MCP 클라이언트에 Mealie 레시피, 식단 계획, 쇼핑 목록, 식품, 단위, 태그, 카테고리 및 레시피 도구를 노출합니다.

기능

• 레시피 검색, 생성, 패치, 업데이트, 복제, URL/HTML/ZIP/이미지 가져오기, 에셋, 이미지, 타임라인 이벤트, 댓글, 내보내기, 제안 및 최근 생성 업데이트

• 가구 식단 계획 항목, 오늘의 식사, 무작위 식사 항목 및 식단 계획 규칙

• Mealie v3 가구 쇼핑 목록, 쇼핑 항목 CRUD, 대량 항목 변경, 레시피-목록 작업 및 라벨 설정

• 별칭, 복수형 이름, 중복 식품 병합 및 중복 단위 병합을 포함한 식품 및 단위 마스터 데이터

• 태그, 카테고리, 레시피 도구/조리 도구, 요리책, 댓글, 공유 링크, 파서, 미디어, 사용자, 그룹, 가구, 탐색 엔드포인트 및 관리자 엔드포인트

• 상태 확인 엔드포인트 및 비루트 컨테이너 사용자를 포함한 Docker 우선 배포

Related MCP server: Mealie MCP Server

요구 사항

• Mealie v3.x

• Mealie API 토큰

• Docker, Docker Compose 또는 Python 3.12+

• 스트리밍 가능한 HTTP 또는 stdio를 지원하는 MCP 클라이언트

Docker를 이용한 빠른 시작

docker run -d \
  --name mealie-mcp \
  --restart unless-stopped \
  -p 8080:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e MEALIE_BASE_URL=http://your-mealie-instance:9000 \
  -e MEALIE_API_TOKEN=your-mealie-api-token \
  ghcr.io/nikopol666/mealie-mcp:latest

상태 확인:

curl http://localhost:8080/health

MCP 엔드포인트:

http://localhost:8080/mcp

Docker Compose

예제 환경 파일을 복사하고 Mealie URL과 API 토큰을 입력한 다음 서비스를 시작하세요:

cp .env.example .env
docker compose up -d

기본 단일 서비스 예제는 docker-compose.yml을 참조하세요.

기존 Mealie Docker 네트워크에 연결하려면 docker-compose.integration.yml을 참조하세요.

services:
  mealie-mcp:
    image: ghcr.io/nikopol666/mealie-mcp:latest
    restart: unless-stopped
    ports:
      - "${MCP_HTTP_PORT:-8080}:8080"
    environment:
      MEALIE_BASE_URL: ${MEALIE_BASE_URL:?Set MEALIE_BASE_URL in .env}
      MEALIE_API_TOKEN: ${MEALIE_API_TOKEN:?Set MEALIE_API_TOKEN in .env}

구성

.env.example을 .env로 복사하고 Mealie URL과 API 토큰을 입력하세요.

MCP 클라이언트 설정

스트리밍 가능한 HTTP

클라이언트가 스트리밍 가능한 HTTP를 지원하는 경우 이 엔드포인트를 사용하세요:

http://localhost:8080/mcp

동일한 Docker 네트워크 내부:

http://mealie-mcp:8080/mcp

Stdio

MCP 서버를 로컬 프로세스로 실행하는 클라이언트의 경우:

git clone https://github.com/nikopol666/mealie-mcp.git
cd mealie-mcp
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
export MEALIE_BASE_URL=http://localhost:9000
export MEALIE_API_TOKEN=your-mealie-api-token
python src/main.py --transport stdio

도구 범위

전체 도구 목록 및 페이로드 참고 사항은 docs/TOOL_REFERENCE.md를 참조하세요.

상위 그룹:

• 상태

• 레시피

• 식단 계획

• 쇼핑 목록

• 식품 및 단위

• 태그, 카테고리 및 레시피 도구

• 요리책, 댓글, 공유 링크, 파서, 미디어, 사용자, 그룹, 가구, 탐색 및 관리자 도구

개발

git clone https://github.com/nikopol666/mealie-mcp.git
cd mealie-mcp
python -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
PYTHONPATH=src MEALIE_API_TOKEN=test-token pytest -q

실제 Mealie 인스턴스에 대한 선택적 읽기 전용 스모크 테스트:

export MEALIE_LIVE_SMOKE=1
export MEALIE_BASE_URL=http://localhost:9000
export MEALIE_API_TOKEN=your-mealie-api-token
PYTHONPATH=src pytest tests/test_live_smoke.py -q

스트리밍 가능한 HTTP로 실행:

export MEALIE_BASE_URL=http://localhost:9000
export MEALIE_API_TOKEN=your-mealie-api-token
python src/main.py --transport streamable-http

Docker 이미지 빌드:

docker build -t mealie-mcp:local .

문서

• 배포 가이드

• 도구 참조

• 식단 계획 가이드

• 예제

• 변경 로그

• 기여 가이드

• 지원 가이드

• 보안 정책

보안 참고 사항

• MEALIE_API_TOKEN을 비밀로 취급하세요.

• 신뢰할 수 있는 네트워크에서만 또는 인증 뒤에서 컨테이너를 실행하세요.

• MCP 서버는 구성된 Mealie 토큰의 권한을 사용하여 Mealie 데이터를 생성, 업데이트 및 삭제할 수 있습니다.

• 가능하면 이 서비스를 위해 전용 Mealie API 토큰을 사용하세요. 공개 및 배포 지침은 SECURITY.md를 참조하세요.

호환성

이 프로젝트는 현재 Mealie v3 API를 대상으로 합니다. Mealie는 시간이 지남에 따라 일부 리소스를 그룹 및 가구 범위 간에 이동했습니다. Mealie 업그레이드 후 도구가 실패하면 실패한 엔드포인트를 인스턴스의 /openapi.json과 비교하세요.

라이선스

MIT