fritzmoles-mcp

Ein MCP-Server, der KI-Assistenten (z. B. Claude) Zugriff auf die Telefonie-Funktionen einer FRITZ!Box gibt: Anruflisten (ein-/ausgehend/verpasst), Anrufbeantworter und Sprachnachrichten, Rufsperren, Rufumleitungen und Telefonbuch-Suche. Netzwerk-Administration (WLAN, Portfreigaben, Heimnetz, ...) ist bewusst nicht enthalten.

Zielgruppe: wer Claude als Assistenten fürs (Geschäfts-)Telefon nutzt — "Wer hat heute angerufen?", "Gibt es neue Nachrichten auf dem AB?", "Sperre die Nummer 0900...", "Schalte die Rufumleitung aufs Handy ein".

graph LR
    Host["MCP-Host<br/>(Claude Desktop / Claude Code / ...)"] -->|stdio, JSON-RPC| MCP["fritzmoles-mcp"]
    MCP -->|TR-064 / SOAP| BOX["FRITZ!Box<br/>X_AVM-DE_OnTel, X_AVM-DE_TAM, X_VoIP"]
    MCP -->|HTTP, Listen-XML| BOX

    style MCP fill:#2b6cb0,color:#fff

Die Kommunikation läuft über die offizielle, von AVM dokumentierte TR-064-Schnittstelle (via fritzconnection). Kein Scraping der Weboberfläche. Getestet gegen eine FRITZ!Box 7490 mit FRITZ!OS 7.62.

Tools

Anruflisten & Rufnummern

Anrufbeantworter (TAM)

Rufsperren

Rufumleitungen

Wählhilfe

✏️ = verändert den Zustand der Box. Mit FRITZ_READ_ONLY=true werden diese Tools gar nicht erst registriert.

Alle Tools liefern ein Dict; im Fehlerfall {"error": "..."} statt einer Exception, damit der Assistent die Ursache (falsche Zugangsdaten, fehlende Rechte, ungültiger Index, ...) lesen kann.

Was TR-064 nicht kann

• Rufumleitungen anlegen oder löschen. AVM stellt per TR-064 nur GetDeflections / SetDeflectionEnable bereit. Regeln einmal in der Weboberfläche anlegen (Telefonie → Rufbehandlung → Rufumleitung), dann per Claude ein-/ausschalten.
• Rufsperren für ausgehende Rufnummernbereiche (0900, Ausland, ...) — TR-064 kennt nur die Sperrliste für eingehende Rufnummern.
• Sprachnachrichten in Text umwandeln. download_voicemail legt die Aufnahme als Datei ab; die Transkription muss ein anderes Werkzeug übernehmen.

Voraussetzungen auf der FRITZ!Box

1. TR-064 aktivieren: Heimnetz → Netzwerk → Netzwerkeinstellungen → "Zugriff für Anwendungen zulassen" (bei neueren FRITZ!OS-Versionen unter "Heimnetzfreigaben").
2. Eigenen Benutzer anlegen (System → FRITZ!Box-Benutzer) mit den Rechten FRITZ!Box Einstellungen und Sprachnachrichten, Faxnachrichten, FRITZ!App Fon und Anrufliste. Kein Admin-Vollzugriff nötig, aber das Recht "Telefonie" (Phone) ist für alle Tools Pflicht.
3. Für dial_number: Telefonie → Anrufe → Wählhilfe aktivieren.

Installation

uvx fritzmoles-mcp          # einmalig ausführen / testen
# oder dauerhaft:
uv tool install fritzmoles-mcp

Konfiguration (ENV oder .env)

Zugangsdaten kommen ausschließlich aus Umgebungsvariablen oder einer .env-Datei im Arbeitsverzeichnis (siehe .env.example). Gesetzte Umgebungsvariablen haben Vorrang vor .env.

Claude Code

claude mcp add --scope user fritzmoles \
  -e FRITZ_HOST=fritz.box -e FRITZ_USERNAME=... -e FRITZ_PASSWORD=... \
  -- uvx fritzmoles-mcp

Wer die Zugangsdaten nicht in ~/.claude.json haben möchte, registriert stattdessen ein kleines Wrapper-Skript, das FRITZ_* aus einem Secret-Store (z. B. OpenBao/Vault, KeePass, pass) exportiert und dann exec uvx fritzmoles-mcp aufruft.

Claude Desktop

claude_desktop_config.json (siehe mcp.example.json):

{
  "mcpServers": {
    "fritzmoles": {
      "command": "uvx",
      "args": ["fritzmoles-mcp"],
      "env": {
        "FRITZ_HOST": "fritz.box",
        "FRITZ_USERNAME": "fritz1234",
        "FRITZ_PASSWORD": "..."
      }
    }
  }
}

Entwicklung

git clone https://github.com/the78mole/fritzmoles-mcp.git
cd fritzmoles-mcp
uv sync --extra dev
uv run pytest                 # Unit-Tests mit Coverage (ohne Box, über eine Fake-Verbindung)
uv run ruff check . && uv run ruff format .
pre-commit install

Gegen eine echte Box testen:

cp .env.example .env          # Zugangsdaten eintragen
uv run mcp dev src/fritzmoles_mcp/server.py   # MCP Inspector

Siehe CONTRIBUTING.md für Commit-Konventionen (Conventional Commits steuern die automatische Versionierung) und den Release-Ablauf.

Lizenz

MIT — Daniel Glaser