Anova Precision Oven 라이브러리 + MCP 서버

이 프로젝트는 의도적으로 분리된 두 개의 계층을 포함합니다:

• anova_oven: Anova 인증, 기기 검색, 온도, 조리 제어, 단계, APO 2.0 WebRTC 카메라 프레임을 위한 비동기 Python 라이브러리.

• anova_oven_mcp: 해당 라이브러리 위에 얇은 MCP 2.x 어댑터.

이 분리를 통해 MCP를 핵심 의존성으로 만들지 않으면서 기기 코드를 향후 Raspberry Pi 서비스나 확장 기능에서 재사용할 수 있습니다.

기능

• JPEG 카메라 프레임 1장을 캡처하거나 비동기 반복자로 프레임을 소비합니다.

• 건식 상부, 건식 하부, 습구, 식품 프로브의 네 가지 물리적 조리 센서를 읽습니다. 활성 건식 제어 값은 별도로 반환됩니다.

• 조리를 시작하고 중지합니다. 시간 제한 단계는 1초부터 오븐 최대치인 359,940초(99시간 59분)까지 지원하며, 기간을 생략하면 중지할 때까지 실행됩니다.

• 프로브 종료 조리와 순차, 시간 제한, 예열 지연 또는 수동 진행 단계를 사용합니다.

• 활성 조리의 단계 목록을 교체합니다.

• UTC 시간을 시, 분, 초로 반환합니다.

• macOS 키체인, 권한 0600의 개인 파일, 또는 주입된 환경 비밀번호에서 자격 증명을 로드합니다.

Related MCP server: Mealie MCP Server

중요 상태 및 안전 참고 사항

조리 명령은 실제로 가전제품을 작동시킵니다. 조리를 시작하거나 변경하는 MCP 도구는 acknowledge_physical_action=true를 요구하며, 오븐의 문서화된 온도, 타이머, 프로브, 발열체, 증기, 팬, 랙 한계를 검증합니다.

카메라 경로는 Anova의 문서화된 Personal Access Token 명령 표면의 일부가 아닌 비공개 모바일 앱 프로토콜입니다. 현재 다음이 필요합니다:

• Anova Precision Oven 2.0

• 활성 조리

• 호환 가능한/최신 펌웨어

• 자격을 갖춘 Anova 구독

라이브 비디오 명령 또는 응답 형태는 향후 Anova 앱/백엔드 릴리스에서 변경될 수 있습니다. 서명된 재생 URL은 내부적으로 유지되며 라이브러리나 MCP 서버에서 절대 반환되지 않습니다.

완료된 실시간 센서, 조리, 카메라 및 테스트 후 안전 점검은 VALIDATION.md를 참조하세요.

설치

Python 3.11 이상이 필요합니다. Python 3.12를 권장합니다.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[server]"

MCP나 비디오 없이 라이브러리만 사용하는 경우:

python -m pip install -e .

선택적 확장 기능은 camera, mcp, server, test입니다. 기본 설치로 핵심 라이브러리를 가볍게 유지하며, anova-oven-mcp 명령은 선택적 런타임이 없을 경우 mcp 또는 server 확장 기능을 설치하도록 안내합니다.

자격 증명

기본 자격 증명 검색 순서는 다음과 같습니다:

1. ANOVA_FIREBASE_REFRESH_TOKEN

2. ANOVA_FIREBASE_REFRESH_TOKEN_FILE이 지정하는 파일

3. 다음 조건의 macOS 키체인 일반 비밀번호 항목:

   • 서비스 com.codex.anova-camera.firebase-refresh-token

   • 계정 anova-oven-mcp

고정된 키체인 계정 레이블은 동일한 서비스 아래의 이전 자격 증명이 실수로 선택되는 것을 방지합니다. 키체인 읽기와 토큰 회전은 Apple의 Security 프레임워크를 직접 사용하므로 비밀번호가 프로세스 인자에 포함되지 않습니다.

리프레시 토큰을 소스 코드, MCP 구성, 셸 기록 또는 로그에 넣지 마십시오. Pi의 경우 호스트 비밀 관리자 또는 root 소유의 권한 0600 자격 증명 파일이 권장 어댑터입니다:

chmod 600 /run/credentials/anova-refresh-token
export ANOVA_FIREBASE_REFRESH_TOKEN_FILE=/run/credentials/anova-refresh-token

둘 이상의 오븐이 페어링된 경우 프로세스 환경에 ANOVA_OVEN_ID를 설정하세요. MCP 기기 목록 도구는 의도적으로 ID만 수정된 형태로 반환합니다. 전체 ID는 모델이 볼 수 있는 컨텍스트 밖에서 구성하세요.

MCP 서버

로컬 기본값은 stdio이므로 수신 포트를 열지 않습니다:

.venv/bin/anova-oven-mcp

일반적인 데스크톱 MCP 구성은 다음과 같습니다:

{
  "mcpServers": {
    "anova-oven": {
      "command": "/absolute/path/to/anova-oven-mcp/.venv/bin/anova-oven-mcp"
    }
  }
}

사용 가능한 도구:

Claude Code 및 Claude Desktop

포함된 구성 도구는 이 로컬 stdio 서버를 Claude Code, Claude Desktop 또는 둘 다에 등록할 수 있습니다. Anova 자격 증명을 두 클라이언트에 복사하지 않습니다.

먼저 변경 사항을 미리 봅니다:

python scripts/configure_claude.py --dry-run

두 클라이언트를 모두 구성합니다(Claude Code는 기본적으로 사용자 범위 사용):

python scripts/configure_claude.py --target both

유용한 대안:

# One client only
python scripts/configure_claude.py --target code
python scripts/configure_claude.py --target desktop

# Update an existing same-named Claude Code entry
python scripts/configure_claude.py --target code --replace

# Remove the entry from both clients
python scripts/configure_claude.py --remove

Claude Desktop 구성은 원자적으로 병합되어 다른 서버를 보존하고 타임스탬프가 있는 권한 0600 백업을 생성합니다. 이후 Claude Desktop을 종료하고 다시 여세요. 로컬 체크아웃을 넘어 배포하려면 Anthropic이 현재 선호하는 형식은 설치 가능한 MCP 번들(.mcpb)입니다.

향후 Pi 서비스를 위해 동일한 어댑터가 Streamable HTTP를 사용할 수 있습니다:

anova-oven-mcp --transport streamable-http

이는 127.0.0.1:8766에 바인딩됩니다. 루프백이 아닌 바인딩에는 --allow-lan이 필요합니다. 인증된 역방향 프록시나 MCP 권한 부여 계층이 준비될 때까지 노출하지 마십시오.

라이브러리 예제

import asyncio

from anova_oven import CookPlan, CookingStage, PrecisionOvenClient


async def main() -> None:
    async with PrecisionOvenClient() as oven:
        temperatures = await oven.get_temperatures()
        print(temperatures.as_dict())

        plan = CookPlan(
            title="Two-stage example",
            stages=(
                CookingStage(
                    title="Warm",
                    target_celsius=60,
                    duration_seconds=600,
                ),
                CookingStage(
                    title="Finish",
                    target_celsius=180,
                    duration_seconds=300,
                ),
            ),
        )

        # This physically starts the oven:
        receipt = await oven.start_cook(plan)
        print(receipt.stage_ids)

        try:
            frame = await oven.capture_frame(timeout=60)
            with open("oven-frame.jpg", "wb") as output:
                output.write(frame.jpeg_bytes)
        finally:
            await oven.stop_cook()


asyncio.run(main())

반복 프레임의 경우 oven.frames()를 비동기 반복자로 사용하세요. MCP는 의도적으로 일회성 이미지를 노출합니다. 무기한 스트리밍 도구 호출은 호스트 간 이식성이 낮기 때문입니다.

검증

python -m pip install -e ".[server,test]"
ruff check .
mypy src
pytest
python -m pip check

읽기 전용 계정 확인은 다음과 같습니다:

python scripts/live_read_only.py

보호된 카메라 스모크 테스트는 최소 온도 3분 조리를 시작하고, 해당 조리를 확인하는 독립적인 상태 이벤트를 기다린 후, 프레임 1장을 캡처하고, 최선의 미디어 정리 전에 물리적 중지를 실행합니다:

python scripts/live_camera_smoke.py --acknowledge-empty-oven-and-start-cook

해당 테스트는 APO 2.0에서 성공적으로 완료되었습니다. 캡처된 검증 프레임은 oven-camera-smoke.jpg로 포함되어 있습니다.

프로토콜 출처

• Anova Wi-Fi 인증

• Anova 기기 검색

• Anova 오븐 명령 및 v2 단계 예제

• 공식 Anova Wi-Fi 참조 프로젝트

• 공식 MCP Python SDK