Anova Precision Oven-Bibliothek + MCP-Server

Dieses Projekt enthält zwei bewusst getrennte Ebenen:

• anova_oven: eine asynchrone Python-Bibliothek für Anova-Authentifizierung, Geräteerkennung, Temperaturen, Kochsteuerung, Stufen und APO 2.0 WebRTC-Kamerabilder.

• anova_oven_mcp: ein schlanker MCP-2.x-Adapter über dieser Bibliothek.

Die Trennung hält den Gerätecode für einen zukünftigen Raspberry-Pi-Dienst oder eine Erweiterung wiederverwendbar, ohne MCP zu einer Kernabhängigkeit zu machen.

Funktionen

• Ein JPEG-Kamerabild aufnehmen oder Frames als asynchronen Iterator verarbeiten.

• Die vier physischen Kochensensoren lesen: trockene Oberseite, trockene Unterseite, Feuchtkugel und Lebensmittelsonde. Der aktive Trockensteuerungswert wird separat zurückgegeben.

• Kochvorgänge starten und stoppen. Zeitgesteuerte Stufen unterstützen 1 Sekunde bis zum Maximum des Ofens von 359.940 Sekunden (99h 59m); eine ausgelassene Dauer läuft, bis sie gestoppt wird.

• Sondenbeendete Kochvorgänge und sequenzielle, zeitgesteuerte, vorheizverzögerte oder manuell fortgeschrittene Stufen verwenden.

• Die Stufenliste eines aktiven Kochvorgangs ersetzen.

• Die UTC-Uhrzeit als Stunden, Minuten und Sekunden zurückgeben.

• Anmeldeinformationen aus dem macOS Keychain, einer privaten Datei mit Modus 0600 oder einem injizierten Umgebungsgeheimnis laden.

Related MCP server: Mealie MCP Server

Wichtige Status- und Sicherheitshinweise

Kochbefehle aktivieren physisch ein Gerät. Die MCP-Tools, die einen Kochvorgang starten oder ändern, erfordern acknowledge_physical_action=true und validieren die dokumentierten Grenzwerte des Ofens für Temperatur, Timer, Sonde, Heizelement, Dampf, Lüfter und Einschub.

Der Kamerapfad ist ein privates Mobile-App-Protokoll, nicht Teil der dokumentierten Personal-Access-Token-Befehlsoberfläche von Anova. Er erfordert derzeit:

• Anova Precision Oven 2.0

• einen aktiven Kochvorgang

• kompatible/aktuelle Firmware

• ein berechtigtes Anova-Abonnement

Die Form des Live-Video-Befehls oder der Antwort kann sich mit einer zukünftigen Anova-App/Backend-Version ändern. Signierte Wiedergabe-URLs werden intern gehalten und niemals von der Bibliothek oder dem MCP-Server zurückgegeben.

Siehe VALIDATION.md für die abgeschlossenen Live-Sensor-, Koch-, Kamera- und Nachtest-Sicherheitsprüfungen.

Installation

Python 3.11 oder neuer ist erforderlich. Python 3.12 wird empfohlen.

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

Für die Bibliotheksnutzung ohne MCP oder Video:

python -m pip install -e .

Optionale Extras sind camera, mcp, server und test. Eine Basisinstallation hält die Kernbibliothek schlank; der Befehl anova-oven-mcp weist Sie an, das Extra mcp oder server zu installieren, wenn seine optionale Laufzeit fehlt.

Anmeldeinformationen

Die Standard-Suchreihenfolge für Anmeldeinformationen ist:

1. ANOVA_FIREBASE_REFRESH_TOKEN

2. die Datei, die durch ANOVA_FIREBASE_REFRESH_TOKEN_FILE benannt ist

3. macOS-Keychain-Element für generische Passwörter mit:

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

   • Konto anova-oven-mcp

Das feste Keychain-Kontolabel verhindert, dass eine ältere Anmeldeinformation unter demselben Dienst versehentlich ausgewählt wird. Keychain-Lesezugriffe und Token-Rotationen verwenden direkt das Security-Framework von Apple, sodass das Geheimnis nicht in Prozessargumenten platziert wird.

Legen Sie kein Refresh-Token in Quellcode, MCP-Konfiguration, Shell-Verlauf oder Protokolle. Für einen Pi ist ein Host-Geheimnisverwalter oder eine root-eigene Anmeldedatei mit Modus 0600 der empfohlene Adapter:

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

Wenn mehr als ein Ofen gekoppelt ist, setzen Sie ANOVA_OVEN_ID in der Prozessumgebung. Das MCP-Geräteliste-Tool gibt absichtlich nur geschwärzte IDs zurück; konfigurieren Sie die vollständige ID außerhalb des für das Modell sichtbaren Kontexts.

MCP-Server

Der lokale Standard ist stdio, daher wird kein lauschender Port geöffnet:

.venv/bin/anova-oven-mcp

Eine generische Desktop-MCP-Konfiguration sieht wie folgt aus:

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

Verfügbare Tools:

Claude Code und Claude Desktop

Der enthaltene Konfigurator kann diesen lokalen stdio-Server bei Claude Code, Claude Desktop oder beiden registrieren. Er kopiert keine Anova-Anmeldeinformationen in einen der Clients.

Zeigen Sie zuerst eine Vorschau der Änderungen an:

python scripts/configure_claude.py --dry-run

Konfigurieren Sie beide Clients (Claude Code verwendet standardmäßig den Benutzerbereich):

python scripts/configure_claude.py --target both

Nützliche Alternativen:

# 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

Die Claude-Desktop-Konfiguration wird atomar zusammengeführt, wobei andere Server erhalten bleiben und eine mit Zeitstempel versehene Sicherung mit Modus 0600 erstellt wird. Beenden Sie Claude Desktop danach und öffnen Sie es erneut. Für die Verteilung über ein lokales Checkout hinaus ist das derzeit bevorzugte Format von Anthropic ein installierbares MCP-Bundle (.mcpb).

Für einen zukünftigen Pi-Dienst kann derselbe Adapter Streamable HTTP verwenden:

anova-oven-mcp --transport streamable-http

Das bindet an 127.0.0.1:8766. Ein Nicht-Loopback-Bind erfordert --allow-lan; setzen Sie es nicht aus, bis ein authentifizierter Reverse-Proxy oder eine MCP-Autorisierungsschicht vorhanden ist.

Bibliotheksbeispiel

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

Für wiederholte Frames verwenden Sie oven.frames() als asynchronen Iterator. MCP stellt absichtlich Einzelbilder bereit, da unbegrenzt gestreamte Tool-Aufrufe zwischen Hosts schlecht portierbar sind.

Verifizierung

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

Die schreibgeschützte Kontoprüfung ist:

python scripts/live_read_only.py

Der geschützte Kamera-Smoke-Test startet einen dreiminütigen Kochvorgang bei Mindesttemperatur, wartet auf ein unabhängiges Zustandsereignis, das diesen Kochvorgang bestätigt, erfasst ein Bild und führt den physischen Stopp vor der Best-Effort-Medienbereinigung aus:

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

Dieser Test wurde erfolgreich gegen eine APO 2.0 abgeschlossen. Das erfasste Validierungsbild ist als oven-camera-smoke.jpg enthalten.

Protokollquellen

• Anova-Wi-Fi-Authentifizierung

• Anova-Geräteerkennung

• Anova-Ofenbefehle und v2-Stufenbeispiele

• Offizielles Anova-Wi-Fi-Referenzprojekt

• Offizielles MCP-Python-SDK