Biblioteca Anova Precision Oven + servidor MCP

Este proyecto contiene dos capas deliberadamente separadas:

• anova_oven: una biblioteca de Python asíncrona para la autenticación de Anova, el descubrimiento de dispositivos, las temperaturas, el control de cocción, las etapas y los fotogramas de cámara WebRTC de APO 2.0.

• anova_oven_mcp: un adaptador ligero de MCP 2.x sobre esa biblioteca.

La separación mantiene el código del dispositivo reutilizable en un futuro servicio o extensión para Raspberry Pi, sin hacer de MCP una dependencia central.

Características

• Capturar un fotograma JPEG de cámara o consumir fotogramas como iterador asíncrono.

• Leer los cuatro sensores físicos de cocción: seco superior, seco inferior, bulbo húmedo y sonda de alimentos. El valor activo de control en seco se devuelve por separado.

• Iniciar y detener cocciones. Las etapas programadas admiten desde 1 segundo hasta el máximo del horno de 359.940 segundos (99 h 59 min); una duración omitida se ejecuta hasta que se detenga.

• Usar cocciones finalizadas por sonda y etapas secuenciales, programadas, con precalentamiento diferido o avanzadas manualmente.

• Reemplazar la lista de etapas de una cocción activa.

• Devolver la hora del día en UTC como horas, minutos y segundos.

• Cargar credenciales desde el Llavero de macOS, un archivo privado con modo 0600 o un secreto de entorno inyectado.

Related MCP server: Mealie MCP Server

Notas importantes de estado y seguridad

Los comandos de cocción activan físicamente un aparato. Las herramientas MCP que inician o modifica una cocción requieren acknowledge_physical_action=true y validan los límites documentados del horno de temperatura, temporizador, sonda, resistencia, vapor, ventilador y rejillas.

La ruta de la cámara es un protocolo privado de la aplicación móvil, no forma parte del surface de comandos documentado de Anova con token de acceso personal. y actualmente requiere:

• Anova Precision Oven 2.0

• una cocción activa

• firmware compatible/actualizado

• una de Anova elegible

The shape of the command or response for the video en vivo may change in the future with a new release of the app/backend from Anova. The signed playback URLs are kept internally and are never returned by the library or the MCP server.

See VALIDATION.md for the live security checks implemented on the sensor, cooking, camera, and post-test.

Instalación

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

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

To use the library without MCP and video:

python -m pip install -e .

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

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:

   • service com.codex.anova-camera.firebase-refresh-token

   • account ova-oven-mcp

The fixed Keychain account 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 device-list MCP tool deliberately returns only redacted IDs; configure the full ID outside model-visible context.

MCP server

The local default is stdio, so no listener port is opened:

.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:

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 distribution 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-fastbind 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 device 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 the 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