Anova Precision Oven library + MCP server

This project contains two deliberately separate layers:

• anova_oven: an async Python library for Anova authentication, device discovery, temperatures, cook control, stages, and APO 2.0 WebRTC camera frames.
• anova_oven_mcp: a thin MCP 2.x adapter over that library.

The separation keeps the device code reusable in a future Raspberry Pi service or extension without making MCP a core dependency.

Features

• Capture one JPEG camera frame or consume frames as an async iterator.
• Read the four physical cooking sensors: dry top, dry bottom, wet bulb, and food probe. The active dry control value is returned separately.
• Start and stop cooks. Timed stages support 1 second through the oven's maximum of 359,940 seconds (99h 59m); an omitted duration runs until stopped.
• Use probe-terminated cooks and sequential, timed, preheat-delayed, or manually advanced stages.
• Replace the stage list of an active cook.
• Return UTC time-of-day as hours, minutes, and seconds.
• Load credentials from macOS Keychain, a private mode-0600 file, or an injected environment secret.

Important status and safety notes

Cook commands physically activate an appliance. The MCP tools that start or alter a cook require acknowledge_physical_action=true, and validate the oven's documented temperature, timer, probe, heating-element, steam, fan, and rack limits.

The camera path is a private mobile-app protocol, not part of Anova's documented Personal Access Token command surface. It currently requires:

• Anova Precision Oven 2.0
• an active cook
• compatible/current firmware
• an eligible Anova subscription

The live-video command or response shape may change with a future Anova app/backend release. Signed playback URLs are kept internal and are never returned by the library or MCP server.

See VALIDATION.md for the completed live sensor, cook, camera, and post-test safety checks.

Installation

Python 3.11 or newer is required. Python 3.12 is recommended.

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

For library use without MCP or video:

python -m pip install -e .

Optional extras are camera, mcp, server, and test. A base install keeps the core library lightweight; the anova-oven-mcp command will direct you to install the mcp or server extra if its optional runtime is absent.

Credentials

The default credential search order is:

1. ANOVA_FIREBASE_REFRESH_TOKEN
2. the file named by ANOVA_FIREBASE_REFRESH_TOKEN_FILE
3. macOS Keychain generic-password item with:
   • service com.codex.anova-camera.firebase-refresh-token
   • account anova-oven-mcp

The fixed Keychain account label prevents an older credential under the same service from being selected accidentally. Keychain reads and token rotations use Apple's Security framework directly, so the secret is not placed in process arguments.

Do not put a refresh token in source, MCP configuration, shell history, or logs. For a Pi, a host secret manager or a root-owned mode-0600 credential file is the recommended adapter:

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

If more than one oven is paired, set ANOVA_OVEN_ID in the process environment. The MCP device-list tool deliberately returns only redacted IDs; configure the full ID outside model-visible context.

MCP server

The local default is stdio, so it opens no listening port:

.venv/bin/anova-oven-mcp

A generic desktop MCP configuration looks like:

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

Available tools:

Tool	Purpose
oven_list_devices	List paired ovens with redacted IDs
oven_get_temperatures	Read all four physical sensors and dry-control value
oven_get_camera_frame	Return one image/jpeg MCP image
oven_start_cook	Start a one-stage timed, probe, or unbounded cook
oven_start_staged_cook	Start a multi-stage cook
oven_configure_stages	Replace stages in the active cook
oven_start_stage	Advance to a configured stage UUID
oven_stop_cook	Stop cooking and close live video
get_utc_time	Return UTC hours, minutes, and seconds

Claude Code and Claude Desktop

The included configurator can register this local stdio server with Claude Code, Claude Desktop, or both. It does not copy Anova credentials into either client.

Preview the changes first:

python scripts/configure_claude.py --dry-run

Configure both clients (Claude Code uses user scope by default):

python scripts/configure_claude.py --target both

Useful alternatives:

# 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 configuration is merged atomically, preserving other servers and creating a timestamped mode-0600 backup. Quit and reopen Claude Desktop afterward. For distributing this beyond a local checkout, Anthropic's current preferred format is an installable MCP Bundle (.mcpb).

For a future Pi service, the same adapter can use Streamable HTTP:

anova-oven-mcp --transport streamable-http

That binds to 127.0.0.1:8766. A non-loopback bind requires --allow-lan; do not expose it until an authenticated reverse proxy or MCP authorization layer is in place.

Library example

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())

For repeated frames, use oven.frames() as an async iterator. MCP intentionally exposes one-shot images because indefinitely streaming tool calls are poorly portable between hosts.

Verification

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

The read-only account check is:

python scripts/live_read_only.py

The guarded camera smoke test starts a minimum-temperature three-minute cook, waits for an independent state event confirming that cook, captures one frame, and issues the physical stop before best-effort media cleanup:

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

That test completed successfully against an APO 2.0. The captured validation frame is included as oven-camera-smoke.jpg.

Protocol sources

• Anova Wi-Fi authentication
• Anova device discovery
• Anova oven commands and v2 stage examples
• Official Anova Wi-Fi reference project
• Official MCP Python SDK