fritzos8-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. fritzos8_mcp-0.1.0/LICENSE +21 -0
  2. fritzos8_mcp-0.1.0/NOTICE +97 -0
  3. fritzos8_mcp-0.1.0/PKG-INFO +153 -0
  4. fritzos8_mcp-0.1.0/README.md +104 -0
  5. fritzos8_mcp-0.1.0/pyproject.toml +150 -0
  6. fritzos8_mcp-0.1.0/pyproject.toml.orig +128 -0
  7. fritzos8_mcp-0.1.0/src/fritzos8_mcp/__init__.py +52 -0
  8. fritzos8_mcp-0.1.0/src/fritzos8_mcp/access.py +186 -0
  9. fritzos8_mcp-0.1.0/src/fritzos8_mcp/alerts.py +387 -0
  10. fritzos8_mcp-0.1.0/src/fritzos8_mcp/anomaly.py +409 -0
  11. fritzos8_mcp-0.1.0/src/fritzos8_mcp/anonymize.py +363 -0
  12. fritzos8_mcp-0.1.0/src/fritzos8_mcp/auth.py +203 -0
  13. fritzos8_mcp-0.1.0/src/fritzos8_mcp/cleanup.py +581 -0
  14. fritzos8_mcp-0.1.0/src/fritzos8_mcp/clienttest.py +276 -0
  15. fritzos8_mcp-0.1.0/src/fritzos8_mcp/config.py +213 -0
  16. fritzos8_mcp-0.1.0/src/fritzos8_mcp/confirm.py +129 -0
  17. fritzos8_mcp-0.1.0/src/fritzos8_mcp/connectivity.py +433 -0
  18. fritzos8_mcp-0.1.0/src/fritzos8_mcp/devices.py +416 -0
  19. fritzos8_mcp-0.1.0/src/fritzos8_mcp/diagnose.py +443 -0
  20. fritzos8_mcp-0.1.0/src/fritzos8_mcp/dns.py +165 -0
  21. fritzos8_mcp-0.1.0/src/fritzos8_mcp/doctor.py +578 -0
  22. fritzos8_mcp-0.1.0/src/fritzos8_mcp/errors.py +109 -0
  23. fritzos8_mcp-0.1.0/src/fritzos8_mcp/family.py +125 -0
  24. fritzos8_mcp-0.1.0/src/fritzos8_mcp/fritzcode.py +484 -0
  25. fritzos8_mcp-0.1.0/src/fritzos8_mcp/guard.py +262 -0
  26. fritzos8_mcp-0.1.0/src/fritzos8_mcp/guestwifi.py +303 -0
  27. fritzos8_mcp-0.1.0/src/fritzos8_mcp/health.py +201 -0
  28. fritzos8_mcp-0.1.0/src/fritzos8_mcp/history.py +508 -0
  29. fritzos8_mcp-0.1.0/src/fritzos8_mcp/httpserve.py +224 -0
  30. fritzos8_mcp-0.1.0/src/fritzos8_mcp/ispreport.py +253 -0
  31. fritzos8_mcp-0.1.0/src/fritzos8_mcp/landevice.py +198 -0
  32. fritzos8_mcp-0.1.0/src/fritzos8_mcp/lanports.py +217 -0
  33. fritzos8_mcp-0.1.0/src/fritzos8_mcp/line.py +473 -0
  34. fritzos8_mcp-0.1.0/src/fritzos8_mcp/mqttbridge.py +342 -0
  35. fritzos8_mcp-0.1.0/src/fritzos8_mcp/multibox.py +130 -0
  36. fritzos8_mcp-0.1.0/src/fritzos8_mcp/myfritz.py +396 -0
  37. fritzos8_mcp-0.1.0/src/fritzos8_mcp/nas.py +398 -0
  38. fritzos8_mcp-0.1.0/src/fritzos8_mcp/nasremote.py +262 -0
  39. fritzos8_mcp-0.1.0/src/fritzos8_mcp/netinfo.py +597 -0
  40. fritzos8_mcp-0.1.0/src/fritzos8_mcp/optimizer.py +528 -0
  41. fritzos8_mcp-0.1.0/src/fritzos8_mcp/oui.py +341 -0
  42. fritzos8_mcp-0.1.0/src/fritzos8_mcp/parental.py +418 -0
  43. fritzos8_mcp-0.1.0/src/fritzos8_mcp/paths.py +62 -0
  44. fritzos8_mcp-0.1.0/src/fritzos8_mcp/phone.py +343 -0
  45. fritzos8_mcp-0.1.0/src/fritzos8_mcp/phonewrite.py +348 -0
  46. fritzos8_mcp-0.1.0/src/fritzos8_mcp/portforward.py +230 -0
  47. fritzos8_mcp-0.1.0/src/fritzos8_mcp/prompts.py +46 -0
  48. fritzos8_mcp-0.1.0/src/fritzos8_mcp/py.typed +0 -0
  49. fritzos8_mcp-0.1.0/src/fritzos8_mcp/quality.py +237 -0
  50. fritzos8_mcp-0.1.0/src/fritzos8_mcp/redact.py +202 -0
  51. fritzos8_mcp-0.1.0/src/fritzos8_mcp/rest.py +145 -0
  52. fritzos8_mcp-0.1.0/src/fritzos8_mcp/rights.py +249 -0
  53. fritzos8_mcp-0.1.0/src/fritzos8_mcp/schemas.py +228 -0
  54. fritzos8_mcp-0.1.0/src/fritzos8_mcp/security.py +295 -0
  55. fritzos8_mcp-0.1.0/src/fritzos8_mcp/server.py +917 -0
  56. fritzos8_mcp-0.1.0/src/fritzos8_mcp/service.py +1079 -0
  57. fritzos8_mcp-0.1.0/src/fritzos8_mcp/setupcheck.py +213 -0
  58. fritzos8_mcp-0.1.0/src/fritzos8_mcp/smarthome.py +379 -0
  59. fritzos8_mcp-0.1.0/src/fritzos8_mcp/smarthome_config.py +722 -0
  60. fritzos8_mcp-0.1.0/src/fritzos8_mcp/smarthome_rest.py +595 -0
  61. fritzos8_mcp-0.1.0/src/fritzos8_mcp/snapshot.py +389 -0
  62. fritzos8_mcp-0.1.0/src/fritzos8_mcp/speedtest.py +153 -0
  63. fritzos8_mcp-0.1.0/src/fritzos8_mcp/syswrite.py +684 -0
  64. fritzos8_mcp-0.1.0/src/fritzos8_mcp/telephony.py +280 -0
  65. fritzos8_mcp-0.1.0/src/fritzos8_mcp/toolargs.py +19 -0
  66. fritzos8_mcp-0.1.0/src/fritzos8_mcp/toolref.py +108 -0
  67. fritzos8_mcp-0.1.0/src/fritzos8_mcp/tr064.py +510 -0
  68. fritzos8_mcp-0.1.0/src/fritzos8_mcp/transparency.py +310 -0
  69. fritzos8_mcp-0.1.0/src/fritzos8_mcp/util.py +39 -0
  70. fritzos8_mcp-0.1.0/src/fritzos8_mcp/vpnplc.py +216 -0
  71. fritzos8_mcp-0.1.0/src/fritzos8_mcp/wlan.py +409 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tom Wellnitz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,97 @@
1
+ fritzos8-mcp
2
+ Copyright (c) 2026 Tom Wellnitz
3
+ Licensed under the MIT License (see LICENSE).
4
+
5
+ This project contains code adapted from, or is informed by, the following
6
+ MIT-licensed projects. Their copyright notices and the MIT permission notice
7
+ apply to the respective portions.
8
+
9
+ -------------------------------------------------------------------------------
10
+ 1. Schimmilab/fritzbox-mcp-server — MIT License, Copyright (c) 2026 Schimmilab
11
+ https://github.com/Schimmilab/fritzbox-mcp-server
12
+
13
+ Adapted code:
14
+ - src/fritzos8_mcp/redact.py: text redaction `redact()` (SID patterns,
15
+ URL credentials, URL/HTML-encoded secret variants, minimum secret length)
16
+ from src/fritzbox_mcp/redact.py; extended with structured/field redaction,
17
+ AVM-SID header and login-response patterns and a logging filter.
18
+ - src/fritzos8_mcp/security.py: `PlanStore` (one-time plan/execute tokens bound
19
+ to action + parameters + target identity, 5 min TTL, thread lock) from
20
+ src/fritzbox_mcp/write.py.
21
+ Adopted concepts (own implementation):
22
+ - Environment-gated write/critical tiers, plan → token → execute flow,
23
+ consequence texts for reboot/reconnect, WANIPConn → WANPPPConnection fallback.
24
+
25
+ 2. gr9driver/fritz-mesh-mcp — MIT License, Copyright (c) 2026 James Calvert
26
+ https://github.com/gr9driver/fritz-mesh-mcp
27
+
28
+ Used as a reference for the login_sid.lua version-2 flow (PBKDF2 with MD5
29
+ fallback). The implementation in src/fritzos8_mcp/auth.py was written after
30
+ AVM's technical note and is verified against AVM's published test vectors.
31
+ Its documented caveat that partial radio changes via /api/v0 can reset
32
+ channel/mode fields is the reason src/fritzos8_mcp/wlan.py uses TR-064
33
+ SetEnable instead (no code taken).
34
+
35
+ 3. the78mole/fritzmoles-mcp — MIT License, Copyright (c) 2026 Daniel Glaser
36
+ https://github.com/the78mole/fritzmoles-mcp
37
+
38
+ Adopted concept (own implementation): a narrow `Protocol` for the
39
+ fritzconnection object plus an injectable connection factory, so all TR-064
40
+ logic is testable without a real box.
41
+ Adapted code:
42
+ - src/fritzos8_mcp/telephony.py: call list / TAM list / TAM message parsers,
43
+ the call type table, `parse_fritz_datetime`, `parse_duration_minutes` and the
44
+ query helper for the call list URL, from src/fritzmoles_mcp/parsers.py and
45
+ client.py; switched to defusedxml, reduced to the returned fields (recording
46
+ paths dropped). The structure of the test documents in
47
+ tests/test_telephony.py follows its fixtures (numbers replaced).
48
+
49
+ 4. kbr/fritzconnection — MIT License, Copyright (c) Klaus Bremer
50
+ https://github.com/kbr/fritzconnection
51
+
52
+ Runtime dependency (TR-064 / SOAP / SCPD). Not vendored.
53
+ Adopted convention (own implementation): the guest WLAN fallback "highest
54
+ WLANConfiguration service" from fritzconnection.lib.fritzwlan.FritzGuestWLAN.
55
+
56
+ -------------------------------------------------------------------------------
57
+ Own code ported from TypeScript:
58
+ The /api/v0 landevice client (list, static DHCP, friendly_name, delete), the
59
+ two-name rename logic and get_lan_dns are Python ports of the author's own
60
+ extensions to a local TypeScript MCP server. No code of the third-party base
61
+ of that server was taken over.
62
+
63
+ Runtime data (not bundled):
64
+ Manufacturer names come from the IEEE Registration Authority MA-L registry
65
+ (https://standards-oui.ieee.org/oui/oui.csv), downloaded at runtime and
66
+ cached locally. No vendor database (e.g. GPL-licensed Wireshark "manuf") is
67
+ included in this project.
68
+
69
+ Endpoint hint only (no code taken):
70
+ Meine-smarte-Welt/fritzbox_netzwerk (README states MIT, but the repository
71
+ has no license file) documents the /api/v0/generic/dnscfg and
72
+ /api/v0/generic/ipv6 field names used read-only in src/fritzos8_mcp/dns.py.
73
+
74
+ No code was copied from repositories without a license file or with a
75
+ proprietary license (e.g. dimitree2k/fritzbox-mcp, maxmeis/fritzbox-mcp,
76
+ ghbalf/mcp-fritzbox, kambriso).
77
+
78
+ -------------------------------------------------------------------------------
79
+ MIT permission notice (applies to the portions listed above):
80
+
81
+ Permission is hereby granted, free of charge, to any person obtaining a copy
82
+ of this software and associated documentation files (the "Software"), to deal
83
+ in the Software without restriction, including without limitation the rights
84
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
85
+ copies of the Software, and to permit persons to whom the Software is
86
+ furnished to do so, subject to the following conditions:
87
+
88
+ The above copyright notice and this permission notice shall be included in all
89
+ copies or substantial portions of the Software.
90
+
91
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
92
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
93
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
94
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
95
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
96
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
97
+ SOFTWARE.
@@ -0,0 +1,153 @@
1
+ Metadata-Version: 2.4
2
+ Name: fritzos8-mcp
3
+ Version: 0.1.0
4
+ Summary: Platform MCP server for AVM FRITZ!Box with FRITZ!OS 8 (TR-064 + /api/v0 REST) with tiered write safety
5
+ Keywords: mcp,model-context-protocol,mcp-server,fritzbox,fritz-box,fritzos,tr-064,avm,router,home-assistant,smart-home,llm
6
+ Author: Tom Wellnitz
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ License-File: NOTICE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Environment :: No Input/Output (Daemon)
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Natural Language :: English
17
+ Classifier: Natural Language :: German
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3 :: Only
23
+ Classifier: Topic :: Home Automation
24
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
25
+ Classifier: Topic :: System :: Networking
26
+ Classifier: Topic :: System :: Networking :: Monitoring
27
+ Classifier: Typing :: Typed
28
+ Requires-Dist: defusedxml>=0.7.1
29
+ Requires-Dist: fritzconnection>=1.15.1
30
+ Requires-Dist: httpx>=0.28.1
31
+ Requires-Dist: mcp>=2.3,<3
32
+ Requires-Dist: pydantic>=2.14.3
33
+ Requires-Dist: pyyaml>=6.0.2
34
+ Requires-Dist: keyring>=25 ; extra == 'keyring'
35
+ Requires-Dist: paho-mqtt>=2.1 ; extra == 'mqtt'
36
+ Requires-Dist: segno>=1.6 ; extra == 'qr'
37
+ Maintainer: Tom Wellnitz
38
+ Requires-Python: >=3.12
39
+ Project-URL: Homepage, https://github.com/tomwellnitz/fritzos8-mcp
40
+ Project-URL: Documentation, https://github.com/tomwellnitz/fritzos8-mcp/blob/main/docs/TOOLS.md
41
+ Project-URL: Repository, https://github.com/tomwellnitz/fritzos8-mcp
42
+ Project-URL: Changelog, https://github.com/tomwellnitz/fritzos8-mcp/blob/main/CHANGELOG.md
43
+ Project-URL: Issues, https://github.com/tomwellnitz/fritzos8-mcp/issues
44
+ Project-URL: Security, https://github.com/tomwellnitz/fritzos8-mcp/security/policy
45
+ Provides-Extra: keyring
46
+ Provides-Extra: mqtt
47
+ Provides-Extra: qr
48
+ Description-Content-Type: text/markdown
49
+
50
+ # fritzos8-mcp
51
+
52
+ [![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)
53
+ [![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)
54
+ [![PyPI](https://img.shields.io/pypi/v/fritzos8-mcp)](https://pypi.org/project/fritzos8-mcp/)
55
+ [![Python versions](https://img.shields.io/pypi/pyversions/fritzos8-mcp)](https://pypi.org/project/fritzos8-mcp/)
56
+ [![License: MIT](https://img.shields.io/github/license/tomwellnitz/fritzos8-mcp)](LICENSE)
57
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tomwellnitz/fritzos8-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tomwellnitz/fritzos8-mcp)
58
+
59
+ **English** · [Deutsch](README.de.md)
60
+
61
+ **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.
62
+
63
+ ## What you can ask
64
+
65
+ > **"Why is my internet slow tonight?"**
66
+ > 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.
67
+
68
+ > **"How secure is my FRITZ!Box?"**
69
+ > 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.
70
+
71
+ > **"Clean up devices that haven't been online for three months."**
72
+ > 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.
73
+
74
+ > **"Turn on guest Wi-Fi for two hours."** · **"Boost the living room heating for 30 minutes."** · **"Block this spam number."**
75
+ > Write actions – each one is read back from the box and reported as `verified: true` or `false`.
76
+
77
+ ## Features
78
+
79
+ - **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)
80
+ - **Security** – scored security check, two-factor status, firmware and update overview for all AVM devices
81
+ - **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
82
+ - **Wi-Fi & family** – Wi-Fi channels and settings, guest Wi-Fi with time limit, access profiles, tickets, internet block per device
83
+ - **Telephony** – call list with reverse lookup, answering machines, phone books, call deflection and barring, alarm clocks
84
+ - **Smart home** – thermostats, switches, blinds, energy report, routines, holiday periods (REST API, AHA fallback)
85
+ - **Monitoring** – optional collector for a local measurement series, ISP fault reports, anomaly detection, alerts via webhook, ntfy or Telegram
86
+ - **Multi-box** – manage several boxes from one server, with a family-admin report across all of them
87
+
88
+ About 160 tools in total – see the generated **[tool reference](docs/TOOLS.md)**.
89
+
90
+ ## Quick start
91
+
92
+ **1. Prepare the box.** Enable *Home Network › Network › Network Settings › Allow access for applications* and create a dedicated user under *System › FRITZ!Box Users*.
93
+
94
+ **2. Store the password** in your OS keychain (or use `FRITZ_PASSWORD_FILE` with mode `600`):
95
+
96
+ ```bash
97
+ uvx --from 'fritzos8-mcp[keyring]' keyring set fritzos8-mcp <user>
98
+ ```
99
+
100
+ **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):
101
+
102
+ ```bash
103
+ claude mcp add fritzos8 -s user -e FRITZ_HOST=fritz.box -e FRITZ_USER=<user> -- \
104
+ uvx --from 'fritzos8-mcp[keyring]' fritzos8-mcp
105
+ ```
106
+
107
+ **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.
108
+
109
+ The server starts **read-only**. Enable changes with `FRITZ_ALLOW_WRITE=1`, critical actions additionally with `FRITZ_ALLOW_CRITICAL=1`.
110
+
111
+ ## Safety model
112
+
113
+ | Tier | Enabled by | What it allows |
114
+ |---|---|---|
115
+ | `read` | always | read-only tools |
116
+ | `write` | `FRITZ_ALLOW_WRITE=1` | changes – each one is read back and reports `verified` |
117
+ | `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 |
118
+
119
+ - **Never claims success it didn't see.** If the result can't be read back, you get `verified: false`.
120
+ - **Never bypasses two-factor confirmation.** If the box asks for it, the tool reports `confirmation_required` and explains how to confirm.
121
+ - **Never shows secrets.** Passwords, Wi-Fi keys, PINs, session IDs and VPN keys are redacted from every output, error and log line.
122
+ - **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.
123
+
124
+ Details: [SECURITY.md](SECURITY.md).
125
+
126
+ ## Works with
127
+
128
+ - **Boxes:** FRITZ!OS 8 – tested on FRITZ!Box 7583 (DSL) and 6660 Cable. Reports for other models are welcome: [compatibility](docs/COMPATIBILITY.md).
129
+ - **Clients:** any MCP client – Claude Code, Claude Desktop, Cursor, VS Code, …
130
+ - **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.
131
+ - **Language:** tool descriptions and messages are in German; assistants handle them fine in any conversation language.
132
+
133
+ **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.
134
+
135
+ ## Documentation
136
+
137
+ | | |
138
+ |---|---|
139
+ | [Configuration](docs/configuration.md) | permissions, all environment variables, multiple boxes, client setup |
140
+ | [Tool reference](docs/TOOLS.md) | every tool with tier, required right and parameters |
141
+ | [Remote access](docs/remote.md) | Streamable HTTP with bearer token, e.g. on a Raspberry Pi |
142
+ | [Interface coverage](docs/COVERAGE.md) | what is covered against the official AVM documentation |
143
+ | [Compatibility](docs/COMPATIBILITY.md) · [Fixtures](docs/fixtures.md) | tested models, contributing anonymized box answers |
144
+
145
+ ## Contributing
146
+
147
+ 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.
148
+
149
+ ## License
150
+
151
+ [MIT](LICENSE). Parts are adapted from MIT-licensed projects, see [NOTICE](NOTICE).
152
+
153
+ 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`.
@@ -0,0 +1,104 @@
1
+ # fritzos8-mcp
2
+
3
+ [![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)
4
+ [![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)
5
+ [![PyPI](https://img.shields.io/pypi/v/fritzos8-mcp)](https://pypi.org/project/fritzos8-mcp/)
6
+ [![Python versions](https://img.shields.io/pypi/pyversions/fritzos8-mcp)](https://pypi.org/project/fritzos8-mcp/)
7
+ [![License: MIT](https://img.shields.io/github/license/tomwellnitz/fritzos8-mcp)](LICENSE)
8
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tomwellnitz/fritzos8-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/tomwellnitz/fritzos8-mcp)
9
+
10
+ **English** · [Deutsch](README.de.md)
11
+
12
+ **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.
13
+
14
+ ## What you can ask
15
+
16
+ > **"Why is my internet slow tonight?"**
17
+ > 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.
18
+
19
+ > **"How secure is my FRITZ!Box?"**
20
+ > 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.
21
+
22
+ > **"Clean up devices that haven't been online for three months."**
23
+ > 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.
24
+
25
+ > **"Turn on guest Wi-Fi for two hours."** · **"Boost the living room heating for 30 minutes."** · **"Block this spam number."**
26
+ > Write actions – each one is read back from the box and reported as `verified: true` or `false`.
27
+
28
+ ## Features
29
+
30
+ - **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)
31
+ - **Security** – scored security check, two-factor status, firmware and update overview for all AVM devices
32
+ - **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
33
+ - **Wi-Fi & family** – Wi-Fi channels and settings, guest Wi-Fi with time limit, access profiles, tickets, internet block per device
34
+ - **Telephony** – call list with reverse lookup, answering machines, phone books, call deflection and barring, alarm clocks
35
+ - **Smart home** – thermostats, switches, blinds, energy report, routines, holiday periods (REST API, AHA fallback)
36
+ - **Monitoring** – optional collector for a local measurement series, ISP fault reports, anomaly detection, alerts via webhook, ntfy or Telegram
37
+ - **Multi-box** – manage several boxes from one server, with a family-admin report across all of them
38
+
39
+ About 160 tools in total – see the generated **[tool reference](docs/TOOLS.md)**.
40
+
41
+ ## Quick start
42
+
43
+ **1. Prepare the box.** Enable *Home Network › Network › Network Settings › Allow access for applications* and create a dedicated user under *System › FRITZ!Box Users*.
44
+
45
+ **2. Store the password** in your OS keychain (or use `FRITZ_PASSWORD_FILE` with mode `600`):
46
+
47
+ ```bash
48
+ uvx --from 'fritzos8-mcp[keyring]' keyring set fritzos8-mcp <user>
49
+ ```
50
+
51
+ **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):
52
+
53
+ ```bash
54
+ claude mcp add fritzos8 -s user -e FRITZ_HOST=fritz.box -e FRITZ_USER=<user> -- \
55
+ uvx --from 'fritzos8-mcp[keyring]' fritzos8-mcp
56
+ ```
57
+
58
+ **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.
59
+
60
+ The server starts **read-only**. Enable changes with `FRITZ_ALLOW_WRITE=1`, critical actions additionally with `FRITZ_ALLOW_CRITICAL=1`.
61
+
62
+ ## Safety model
63
+
64
+ | Tier | Enabled by | What it allows |
65
+ |---|---|---|
66
+ | `read` | always | read-only tools |
67
+ | `write` | `FRITZ_ALLOW_WRITE=1` | changes – each one is read back and reports `verified` |
68
+ | `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 |
69
+
70
+ - **Never claims success it didn't see.** If the result can't be read back, you get `verified: false`.
71
+ - **Never bypasses two-factor confirmation.** If the box asks for it, the tool reports `confirmation_required` and explains how to confirm.
72
+ - **Never shows secrets.** Passwords, Wi-Fi keys, PINs, session IDs and VPN keys are redacted from every output, error and log line.
73
+ - **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.
74
+
75
+ Details: [SECURITY.md](SECURITY.md).
76
+
77
+ ## Works with
78
+
79
+ - **Boxes:** FRITZ!OS 8 – tested on FRITZ!Box 7583 (DSL) and 6660 Cable. Reports for other models are welcome: [compatibility](docs/COMPATIBILITY.md).
80
+ - **Clients:** any MCP client – Claude Code, Claude Desktop, Cursor, VS Code, …
81
+ - **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.
82
+ - **Language:** tool descriptions and messages are in German; assistants handle them fine in any conversation language.
83
+
84
+ **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.
85
+
86
+ ## Documentation
87
+
88
+ | | |
89
+ |---|---|
90
+ | [Configuration](docs/configuration.md) | permissions, all environment variables, multiple boxes, client setup |
91
+ | [Tool reference](docs/TOOLS.md) | every tool with tier, required right and parameters |
92
+ | [Remote access](docs/remote.md) | Streamable HTTP with bearer token, e.g. on a Raspberry Pi |
93
+ | [Interface coverage](docs/COVERAGE.md) | what is covered against the official AVM documentation |
94
+ | [Compatibility](docs/COMPATIBILITY.md) · [Fixtures](docs/fixtures.md) | tested models, contributing anonymized box answers |
95
+
96
+ ## Contributing
97
+
98
+ 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.
99
+
100
+ ## License
101
+
102
+ [MIT](LICENSE). Parts are adapted from MIT-licensed projects, see [NOTICE](NOTICE).
103
+
104
+ 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`.
@@ -0,0 +1,150 @@
1
+ [project]
2
+ name = "fritzos8-mcp"
3
+ version = "0.1.0"
4
+ description = "Platform MCP server for AVM FRITZ!Box with FRITZ!OS 8 (TR-064 + /api/v0 REST) with tiered write safety"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = [
8
+ "LICENSE",
9
+ "NOTICE",
10
+ ]
11
+ keywords = [
12
+ "mcp",
13
+ "model-context-protocol",
14
+ "mcp-server",
15
+ "fritzbox",
16
+ "fritz-box",
17
+ "fritzos",
18
+ "tr-064",
19
+ "avm",
20
+ "router",
21
+ "home-assistant",
22
+ "smart-home",
23
+ "llm",
24
+ ]
25
+ classifiers = [
26
+ "Development Status :: 4 - Beta",
27
+ "Environment :: Console",
28
+ "Environment :: No Input/Output (Daemon)",
29
+ "Intended Audience :: End Users/Desktop",
30
+ "Intended Audience :: System Administrators",
31
+ "License :: OSI Approved :: MIT License",
32
+ "Natural Language :: English",
33
+ "Natural Language :: German",
34
+ "Operating System :: OS Independent",
35
+ "Programming Language :: Python :: 3",
36
+ "Programming Language :: Python :: 3.12",
37
+ "Programming Language :: Python :: 3.13",
38
+ "Programming Language :: Python :: 3 :: Only",
39
+ "Topic :: Home Automation",
40
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
41
+ "Topic :: System :: Networking",
42
+ "Topic :: System :: Networking :: Monitoring",
43
+ "Typing :: Typed",
44
+ ]
45
+ requires-python = ">=3.12"
46
+ dependencies = [
47
+ "defusedxml>=0.7.1",
48
+ "fritzconnection>=1.15.1",
49
+ "httpx>=0.28.1",
50
+ "mcp>=2.3,<3",
51
+ "pydantic>=2.14.3",
52
+ "pyyaml>=6.0.2",
53
+ ]
54
+
55
+ [[project.authors]]
56
+ name = "Tom Wellnitz"
57
+
58
+ [[project.maintainers]]
59
+ name = "Tom Wellnitz"
60
+
61
+ [project.urls]
62
+ Homepage = "https://github.com/tomwellnitz/fritzos8-mcp"
63
+ Documentation = "https://github.com/tomwellnitz/fritzos8-mcp/blob/main/docs/TOOLS.md"
64
+ Repository = "https://github.com/tomwellnitz/fritzos8-mcp"
65
+ Changelog = "https://github.com/tomwellnitz/fritzos8-mcp/blob/main/CHANGELOG.md"
66
+ Issues = "https://github.com/tomwellnitz/fritzos8-mcp/issues"
67
+ Security = "https://github.com/tomwellnitz/fritzos8-mcp/security/policy"
68
+
69
+ [project.scripts]
70
+ fritzos8-mcp = "fritzos8_mcp:main"
71
+ fritzos8-collector = "fritzos8_mcp.history:collector_main"
72
+ fritzos8-anonymize = "fritzos8_mcp.anonymize:cli"
73
+
74
+ [project.optional-dependencies]
75
+ qr = ["segno>=1.6"]
76
+ mqtt = ["paho-mqtt>=2.1"]
77
+ keyring = ["keyring>=25"]
78
+
79
+ [build-system]
80
+ requires = ["uv_build>=0.11.15,<0.14.0"]
81
+ build-backend = "uv_build"
82
+
83
+ [dependency-groups]
84
+ dev = [
85
+ "mypy>=2.4.1",
86
+ "pip-audit>=2.10.1",
87
+ "pre-commit>=4.7.0",
88
+ "pytest>=9.2.0",
89
+ "pytest-asyncio>=1.5.0",
90
+ "respx>=0.23.1",
91
+ "ruff>=0.17.5",
92
+ "segno>=1.6",
93
+ "twine>=7.0.0",
94
+ "types-defusedxml>=0.7.0.20260504",
95
+ "types-pyyaml>=6.0.12.20261113",
96
+ ]
97
+ docs = [
98
+ "mkdocs>=1.6.1",
99
+ "mkdocs-material>=9.8.1",
100
+ "mkdocs-static-i18n>=1.3.1",
101
+ ]
102
+
103
+ [tool.pytest.ini_options]
104
+ testpaths = ["tests"]
105
+ asyncio_mode = "auto"
106
+ asyncio_default_fixture_loop_scope = "function"
107
+ addopts = "-q"
108
+ markers = ["live: liest von einer echten FRITZ!Box (nur mit FRITZ_LIVE_TEST=1)"]
109
+
110
+ [tool.ruff]
111
+ line-length = 120
112
+ target-version = "py312"
113
+
114
+ [tool.ruff.lint]
115
+ select = [
116
+ "E",
117
+ "F",
118
+ "W",
119
+ "I",
120
+ "B",
121
+ "UP",
122
+ "S",
123
+ "SIM",
124
+ "RUF",
125
+ ]
126
+ ignore = [
127
+ "RUF001",
128
+ "RUF002",
129
+ "RUF003",
130
+ ]
131
+
132
+ [tool.ruff.lint.per-file-ignores]
133
+ "tests/**" = [
134
+ "S101",
135
+ "S104",
136
+ "S105",
137
+ "S106",
138
+ "B017",
139
+ "RUF012",
140
+ ]
141
+
142
+ [tool.mypy]
143
+ python_version = "3.12"
144
+ strict = true
145
+ packages = ["fritzos8_mcp"]
146
+ mypy_path = "src"
147
+
148
+ [[tool.mypy.overrides]]
149
+ module = ["fritzconnection.*"]
150
+ ignore_missing_imports = true
@@ -0,0 +1,128 @@
1
+ [project]
2
+ name = "fritzos8-mcp"
3
+ version = "0.1.0"
4
+ description = "Platform MCP server for AVM FRITZ!Box with FRITZ!OS 8 (TR-064 + /api/v0 REST) with tiered write safety"
5
+ readme = "README.md"
6
+ authors = [{ name = "Tom Wellnitz" }]
7
+ maintainers = [{ name = "Tom Wellnitz" }]
8
+ license = "MIT"
9
+ license-files = ["LICENSE", "NOTICE"]
10
+ keywords = [
11
+ "mcp",
12
+ "model-context-protocol",
13
+ "mcp-server",
14
+ "fritzbox",
15
+ "fritz-box",
16
+ "fritzos",
17
+ "tr-064",
18
+ "avm",
19
+ "router",
20
+ "home-assistant",
21
+ "smart-home",
22
+ "llm",
23
+ ]
24
+ classifiers = [
25
+ "Development Status :: 4 - Beta",
26
+ "Environment :: Console",
27
+ "Environment :: No Input/Output (Daemon)",
28
+ "Intended Audience :: End Users/Desktop",
29
+ "Intended Audience :: System Administrators",
30
+ "License :: OSI Approved :: MIT License",
31
+ "Natural Language :: English",
32
+ "Natural Language :: German",
33
+ "Operating System :: OS Independent",
34
+ "Programming Language :: Python :: 3",
35
+ "Programming Language :: Python :: 3.12",
36
+ "Programming Language :: Python :: 3.13",
37
+ "Programming Language :: Python :: 3 :: Only",
38
+ "Topic :: Home Automation",
39
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
40
+ "Topic :: System :: Networking",
41
+ "Topic :: System :: Networking :: Monitoring",
42
+ "Typing :: Typed",
43
+ ]
44
+ requires-python = ">=3.12"
45
+ dependencies = [
46
+ "defusedxml>=0.7.1",
47
+ "fritzconnection>=1.15.1",
48
+ "httpx>=0.28.1",
49
+ "mcp>=2.3,<3",
50
+ "pydantic>=2.14.3",
51
+ "pyyaml>=6.0.2",
52
+ ]
53
+
54
+ [project.urls]
55
+ Homepage = "https://github.com/tomwellnitz/fritzos8-mcp"
56
+ Documentation = "https://github.com/tomwellnitz/fritzos8-mcp/blob/main/docs/TOOLS.md"
57
+ Repository = "https://github.com/tomwellnitz/fritzos8-mcp"
58
+ Changelog = "https://github.com/tomwellnitz/fritzos8-mcp/blob/main/CHANGELOG.md"
59
+ Issues = "https://github.com/tomwellnitz/fritzos8-mcp/issues"
60
+ Security = "https://github.com/tomwellnitz/fritzos8-mcp/security/policy"
61
+
62
+ [project.scripts]
63
+ fritzos8-mcp = "fritzos8_mcp:main"
64
+ fritzos8-collector = "fritzos8_mcp.history:collector_main"
65
+ fritzos8-anonymize = "fritzos8_mcp.anonymize:cli"
66
+
67
+ [project.optional-dependencies]
68
+ qr = [
69
+ "segno>=1.6",
70
+ ]
71
+ mqtt = [
72
+ "paho-mqtt>=2.1",
73
+ ]
74
+ keyring = [
75
+ "keyring>=25",
76
+ ]
77
+
78
+ [build-system]
79
+ requires = ["uv_build>=0.11.15,<0.14.0"]
80
+ build-backend = "uv_build"
81
+
82
+ [dependency-groups]
83
+ dev = [
84
+ "mypy>=2.4.1",
85
+ "pip-audit>=2.10.1",
86
+ "pre-commit>=4.7.0",
87
+ "pytest>=9.2.0",
88
+ "pytest-asyncio>=1.5.0",
89
+ "respx>=0.23.1",
90
+ "ruff>=0.17.5",
91
+ "segno>=1.6",
92
+ "twine>=7.0.0",
93
+ "types-defusedxml>=0.7.0.20260504",
94
+ "types-pyyaml>=6.0.12.20261113",
95
+ ]
96
+ docs = [
97
+ "mkdocs>=1.6.1",
98
+ "mkdocs-material>=9.8.1",
99
+ "mkdocs-static-i18n>=1.3.1",
100
+ ]
101
+
102
+ [tool.pytest.ini_options]
103
+ testpaths = ["tests"]
104
+ asyncio_mode = "auto"
105
+ asyncio_default_fixture_loop_scope = "function"
106
+ addopts = "-q"
107
+ markers = ["live: liest von einer echten FRITZ!Box (nur mit FRITZ_LIVE_TEST=1)"]
108
+
109
+ [tool.ruff]
110
+ line-length = 120
111
+ target-version = "py312"
112
+
113
+ [tool.ruff.lint]
114
+ select = ["E", "F", "W", "I", "B", "UP", "S", "SIM", "RUF"]
115
+ ignore = ["RUF001", "RUF002", "RUF003"]
116
+
117
+ [tool.ruff.lint.per-file-ignores]
118
+ "tests/**" = ["S101", "S104", "S105", "S106", "B017", "RUF012"]
119
+
120
+ [tool.mypy]
121
+ python_version = "3.12"
122
+ strict = true
123
+ packages = ["fritzos8_mcp"]
124
+ mypy_path = "src"
125
+
126
+ [[tool.mypy.overrides]]
127
+ module = ["fritzconnection.*"]
128
+ ignore_missing_imports = true