Metadata-Version: 2.4
Name: fritzos8-mcp
Version: 0.1.1
Summary: Platform MCP server for AVM FRITZ!Box with FRITZ!OS 8 (TR-064 + /api/v0 REST) with tiered write safety
Keywords: mcp,model-context-protocol,mcp-server,fritzbox,fritz-box,fritzos,tr-064,avm,router,home-assistant,smart-home,llm
Author: Tom Wellnitz
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: German
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Home Automation
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Typing :: Typed
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: fritzconnection>=1.15.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=2.3,<3
Requires-Dist: pydantic>=2.14.3
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: keyring>=25 ; extra == 'keyring'
Requires-Dist: paho-mqtt>=2.1 ; extra == 'mqtt'
Requires-Dist: segno>=1.6 ; extra == 'qr'
Maintainer: Tom Wellnitz
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/tomwellnitz/fritzos8-mcp
Project-URL: Documentation, https://github.com/tomwellnitz/fritzos8-mcp/blob/main/docs/TOOLS.md
Project-URL: Repository, https://github.com/tomwellnitz/fritzos8-mcp
Project-URL: Changelog, https://github.com/tomwellnitz/fritzos8-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/tomwellnitz/fritzos8-mcp/issues
Project-URL: Security, https://github.com/tomwellnitz/fritzos8-mcp/security/policy
Provides-Extra: keyring
Provides-Extra: mqtt
Provides-Extra: qr
Description-Content-Type: text/markdown

# fritzos8-mcp

[![CI](https://github.com/tomwellnitz/fritzos8-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tomwellnitz/fritzos8-mcp/actions/workflows/ci.yml)
[![CodeQL](https://github.com/tomwellnitz/fritzos8-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/tomwellnitz/fritzos8-mcp/actions/workflows/codeql.yml)
[![PyPI](https://img.shields.io/pypi/v/fritzos8-mcp)](https://pypi.org/project/fritzos8-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/fritzos8-mcp)](https://pypi.org/project/fritzos8-mcp/)
[![License: MIT](https://img.shields.io/github/license/tomwellnitz/fritzos8-mcp)](LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tomwellnitz/fritzos8-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tomwellnitz/fritzos8-mcp)

**English** · [Deutsch](README.de.md)

**Let your AI assistant run your FRITZ!Box – safely.** An [MCP](https://modelcontextprotocol.io) server for AVM FRITZ!Box routers on FRITZ!OS 8: diagnose slow internet, audit security, clean up the device list, manage guest Wi-Fi, telephony and smart home – read-only by default, and every change is verified.

## What you can ask

> **"Why is my internet slow tonight?"**
> Runs the network doctor: line values (SNR margin, errors, resyncs), event log, Wi-Fi and mesh, LAN link flapping, DNS as a single point of failure – and returns findings with severity, likely cause and what to do.

> **"How secure is my FRITZ!Box?"**
> Security check with a 0–100 score: remote access, MyFRITZ!, port forwards, WPS, Wi-Fi encryption, guest isolation, firmware, DNS over TLS – each finding with the exact menu path to fix it.

> **"Clean up devices that haven't been online for three months."**
> Finds candidates (long offline, random MACs, duplicates, orphaned static IPs), suggests better names via vendor lookup, shows you the plan and changes nothing until you confirm.

> **"Turn on guest Wi-Fi for two hours."** · **"Boost the living room heating for 30 minutes."** · **"Block this spam number."**
> Write actions – each one is read back from the box and reported as `verified: true` or `false`.

## Features

- **Diagnostics** – network doctor, line diagnostics for DSL, cable, fibre and LTE, per-device connection quality, link-flapping detection, system transparency (TR-069, NTP, IPv6/DS-Lite)
- **Security** – scored security check, two-factor status, firmware and update overview for all AVM devices
- **Devices** – both device names (TR-064 and web UI), rename, static IP, clean-up assistant, snapshots with diff, Wake-on-LAN, mesh and LAN ports
- **Wi-Fi & family** – Wi-Fi channels and settings, guest Wi-Fi with time limit, access profiles, tickets, internet block per device
- **Telephony** – call list with reverse lookup, answering machines, phone books, call deflection and barring, alarm clocks
- **Smart home** – thermostats, switches, blinds, energy report, routines, holiday periods (REST API, AHA fallback)
- **Monitoring** – optional collector for a local measurement series, ISP fault reports, anomaly detection, alerts via webhook, ntfy or Telegram
- **Multi-box** – manage several boxes from one server, with a family-admin report across all of them

About 160 tools in total – see the generated **[tool reference](docs/TOOLS.md)**.

## Quick start

**1. Prepare the box.** Enable *Home Network › Network › Network Settings › Allow access for applications* and create a dedicated user under *System › FRITZ!Box Users*.

**2. Store the password** in your OS keychain (or use `FRITZ_PASSWORD_FILE` with mode `600`):

```bash
uvx --from 'fritzos8-mcp[keyring]' keyring set fritzos8-mcp <user>
```

**3. Add the server to your client** – Claude Code shown, JSON config for Claude Desktop, Cursor and others in [configuration](docs/configuration.md#client-setup):

```bash
claude mcp add fritzos8 -s user -e FRITZ_HOST=fritz.box -e FRITZ_USER=<user> -- \
  uvx --from 'fritzos8-mcp[keyring]' fritzos8-mcp
```

**4. Ask your assistant to run `setup_check`.** It verifies TR-064, the user's rights and two-factor settings, and tells you which tools a missing right would disable.

The server starts **read-only**. Enable changes with `FRITZ_ALLOW_WRITE=1`, critical actions additionally with `FRITZ_ALLOW_CRITICAL=1`.

## Safety model

| Tier | Enabled by | What it allows |
|---|---|---|
| `read` | always | read-only tools |
| `write` | `FRITZ_ALLOW_WRITE=1` | changes – each one is read back and reports `verified` |
| `critical` | `+ FRITZ_ALLOW_CRITICAL=1` | reboot, port forwards, firmware update, … only via **plan → one-time token → execute**, plus a yes/no prompt in clients that support it |

- **Never claims success it didn't see.** If the result can't be read back, you get `verified: false`.
- **Never bypasses two-factor confirmation.** If the box asks for it, the tool reports `confirmation_required` and explains how to confirm.
- **Never shows secrets.** Passwords, Wi-Fi keys, PINs, session IDs and VPN keys are redacted from every output, error and log line.
- **Protects the box.** Throttling, caching and a circuit breaker per box; `server_status` shows the health of each interface (last success/error, re-logins) even when the client still shows the server as connected.

Details: [SECURITY.md](SECURITY.md).

## Works with

- **Boxes:** FRITZ!OS 8 – tested on FRITZ!Box 7583 (DSL) and 6660 Cable. Reports for other models are welcome: [compatibility](docs/COMPATIBILITY.md).
- **Clients:** any MCP client – Claude Code, Claude Desktop, Cursor, VS Code, …
- **Interfaces:** TR-064 (via [fritzconnection](https://github.com/kbr/fritzconnection)), the AHA and Smart Home REST APIs, and the web UI's `/api/v0` – the latter only where TR-064 can't help.
- **Language:** tool descriptions and messages are in German; assistants handle them fine in any conversation language.

**Not a Home Assistant replacement.** For HA entities use the official *AVM FRITZ!Box Tools*, *FRITZ!SmartHome* and *Call Monitor* integrations. This server is for AI assistants – diagnostics, audits and guarded changes. Alerts can be sent to a Home Assistant webhook.

## Documentation

| | |
|---|---|
| [Configuration](docs/configuration.md) | permissions, all environment variables, multiple boxes, client setup |
| [Tool reference](docs/TOOLS.md) | every tool with tier, required right and parameters |
| [Remote access](docs/remote.md) | Streamable HTTP with bearer token, e.g. on a Raspberry Pi |
| [Interface coverage](docs/COVERAGE.md) | what is covered against the official AVM documentation |
| [Compatibility](docs/COMPATIBILITY.md) · [Fixtures](docs/fixtures.md) | tested models, contributing anonymized box answers |

## Contributing

Bug reports, compatibility reports and pull requests are welcome – see [CONTRIBUTING.md](CONTRIBUTING.md). `make setup` installs everything including the git hooks; tests run against mocks only, no box required.

## License

[MIT](LICENSE). Parts are adapted from MIT-licensed projects, see [NOTICE](NOTICE).

Independent project, not affiliated with AVM / FRITZ! GmbH. FRITZ!Box and FRITZ!OS are trademarks of FRITZ! GmbH. The `/api/v0` endpoints are undocumented and may change with firmware updates; affected tools then report `unsupported_firmware`.
