= FRITZ!Box MCP Server :toc: macro :toclevels: 3 :sectnums:

Control your FRITZ!Box router through AI assistants like Claude using natural language.

link:README-de.adoc[🇩🇪 Deutsche Version] | link:COMPARISON.adoc[Comparison with Other Solutions] | link:CHANGELOG.adoc[Changelog]

https://mcpservers.org/servers/kambriso/fritzbox-mcp-server[image:https://img.shields.io/badge/Listed%20on-mcpservers.org-0066cc?style=for-the-badge&logo=anthropic[Listed on mcpservers.org]]

https://github.com/kambriso/fritzbox-mcp-server/actions/workflows/build.yml[image:https://github.com/kambriso/fritzbox-mcp-server/actions/workflows/build.yml/badge.svg[Build]] https://github.com/kambriso/fritzbox-mcp-server/releases/latest[image:https://img.shields.io/github/v/release/kambriso/fritzbox-mcp-server[Release]] https://gitlab.com/kambriso/fritzbox-mcp-server/-/pipelines[image:https://gitlab.com/kambriso/fritzbox-mcp-server/badges/main/pipeline.svg[Pipeline]] image:https://img.shields.io/badge/SLSA-Level%203-green[SLSA Level 3] image:https://img.shields.io/github/license/kambriso/fritzbox-mcp-server[License] image:https://img.shields.io/github/go-mod/go-version/kambriso/fritzbox-mcp-server[Go Version]

toc::[]

== Introduction

=== What is this?

This MCP server lets you interact with your FRITZ!Box router using AI assistants. Ask questions in plain language, analyze your network, manage devices, troubleshoot issues, and configure settings without touching the web interface.

=== How it works (Security Architecture)

image::arch.svg[Architecture Diagram]

The MCP server runs on your computer and acts as a secure bridge between AI agents (which run in the cloud) and your FRITZ!Box (which stays completely local).

Your FRITZ!Box credentials are stored locally in a .env file on your computer. The MCP server uses these credentials to communicate with your FRITZ!Box over your local network only.

The AI agent receives only the results (like "3 devices connected" or "Router uptime: 5 days"), never your credentials or direct access to your router.

Critical security features:

• Your FRITZ!Box never needs internet exposure
• No ports need to be opened
• No cloud connection to your router
• Credentials stay on your computer
• All router communication happens on your local network only

=== Why use this?

Works with ALL FRITZ!Box models and firmware versions. When AVM releases new features or models, this server adapts automatically. No updates needed.

Unlike other solutions that break with firmware updates or only work with specific models, this server discovers your router's capabilities in real-time.

== User Guide

=== Quick Start

==== 1. Installation

===== Automated Installation (Linux/macOS - Recommended)

Download and install with automatic checksum verification:

[source,bash]

curl -fsSL https://raw.githubusercontent.com/kambriso/fritzbox-mcp-server/main/install.sh | sh

The installer will:

• Detect your platform (OS and architecture) automatically
• Download the latest release from GitHub
• Verify SHA256 checksums for security
• Install to ~/.local/bin/fritz-mcp
• Make the binary executable

[TIP]

Customize installation:

[source,bash]

Install specific version

FRITZBOX_MCP_VERSION= curl -fsSL https://raw.githubusercontent.com/kambriso/fritzbox-mcp-server/main/install.sh | sh

Install to custom directory

FRITZBOX_MCP_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/kambriso/fritzbox-mcp-server/main/install.sh | sh

====

===== Manual Installation (All platforms)

Get the binary for your system from https://github.com/kambriso/fritzbox-mcp-server/releases[Releases]:

Linux:: fritz-mcp-linux-amd64.tar.xz or fritz-mcp-linux-arm64.tar.xz macOS:: fritz-mcp-darwin-amd64.tar.xz or fritz-mcp-darwin-arm64.tar.xz Windows:: fritz-mcp-windows-amd64.zip or fritz-mcp-windows-arm64.zip

Extract the archive and make it executable (Linux/macOS): [source,bash]

tar -xJf fritz-mcp-linux-amd64.tar.xz chmod +x fritz-mcp

Windows: Extract the ZIP file.

==== 2. Interactive Setup

The easiest way to configure your FRITZ!Box is using the interactive setup mode. This will automatically discover your router on the network and guide you through the configuration process.

[source,bash]

./fritz-mcp --setup

The setup mode will:

1. Discover: Find FRITZ!Box devices using SSDP on your local network.
2. Identify: Automatically detect the Mesh Master (gateway).
3. Configure: Prompt for your host, username, password, and TLS preference.
4. Secure: Save credentials to a .env file with 0600 permissions (read/write only by you).

==== 3. FRITZ!Box User Permissions

Your FRITZ!Box user needs full settings access.

In the FRITZ!Box web interface (http://fritz.box):

1. Go to System → FRITZ!Box-Benutzer → [Your User] → Berechtigungen
2. Enable: "FRITZ!Box-Einstellungen" (or "The user can view and edit all FRITZ!Box settings")

==== 4. Configure Claude Desktop (or similar/ analog for your preferred AI assistant)

Edit your Claude Desktop config file:

Windows:: %APPDATA%\Claude\claude_desktop_config.json macOS:: ~/Library/Application Support/Claude/claude_desktop_config.json Linux:: ~/.config/claude/claude_desktop_config.json

Add the server:

[source,json]

{ "mcpServers": { "fritzbox": { "command": "/path/to/fritz-mcp" } } }

[TIP]

Windows: C:\\Users\\YourName\\path\\to\\fritz-mcp.exe (note the double backslashes)

macOS/Linux with automated install: ~/.local/bin/fritz-mcp

macOS/Linux with manual install: Absolute path to where you placed the binary, e.g., /Users/yourname/bin/fritz-mcp

Restart Claude Desktop.

=== What can you do?

==== Ask Questions

"What's my external IP address?"

"Show me all connected devices"

"How long has the router been running?"

"What's my current internet speed?"

"Is my WiFi secure?"

==== Analyze Your Network

"Analyze my network health and tell me if everything looks good"

Claude will check your connection quality, identify issues, explain patterns in your logs, and provide recommendations.

Example response: [source,text]

Network Health Analysis

Connection: Healthy ✓

• Speed: 112 / 37 Mbit/s (down/up)
• Signal quality: Excellent
• No errors detected

Daily Reconnections at 04:00: This is normal. Your ISP enforces 24-hour session limits. FRITZ!Box reconnects proactively to avoid forced disconnection.

One DSL resync on Dec 7 at 12:52: Single event, recovered in 4 minutes. Monitor for recurring patterns, but not concerning as an isolated incident.

Overall: Network operating optimally.

==== Manage Devices

"Show all WiFi devices"

"Which devices are using the most bandwidth?"

"List unknown devices in my network"

"Prioritize my laptop's bandwidth - I have a video call"

==== Parental Controls & Scheduling

"Block the Nintendo Switch in 20 minutes"

"Disable internet for all gaming devices during work hours"

"Enable guest WiFi at 6 PM for the party"

==== Troubleshooting

"Why is my internet slow?"

"Check if there are any connection problems"

"Show me recent disconnections"

=== Examples

==== Network Health Check

Prompt: "Analyze my network health and check if everything is running optimally"

Claude autonomously:

1. Queries device info and uptime
2. Checks connection status and stability
3. Analyzes line quality and error rates
4. Reviews logs for patterns
5. Distinguishes normal behavior from issues
6. Provides recommendations

==== Device Inventory

Prompt: "Show me all devices - which are online and are there any unknown devices?"

Claude:

1. Lists all registered devices
2. Categorizes by status (online/offline)
3. Groups by connection type (WiFi/Ethernet)
4. Identifies unknown or suspicious devices
5. Provides security analysis

==== Time-Delayed Actions

Prompt: "Block the gaming console in 20 minutes"

Claude schedules the action to execute automatically, even after you close the chat.

This uses the server's CLI mode for persistent background execution.

=== Troubleshooting

==== Cannot connect to FRITZ!Box

Check that your router is reachable: [source,bash]

ping fritz.box

Verify credentials in .env file.

Ensure your FRITZ!Box user has full settings permission enabled.

==== Claude Desktop doesn't see the server

Verify the path in claude_desktop_config.json is absolute and correct.

Windows users: Use double backslashes in paths.

Restart Claude Desktop after config changes.

==== Permission errors

Your FRITZ!Box user needs "FRITZ!Box-Einstellungen" permission enabled. See configuration section above.

=== Privacy & Security

All communication stays on your local network. Your credentials are stored locally in a .env file and used only to communicate with your FRITZ!Box. The AI receives only the results of operations, never your credentials.

No cloud services. No external servers. Everything runs locally.

==== Binary Verification

Independent VirusTotal scans confirm the binaries are clean:

• https://www.virustotal.com/gui/file/3137edfa6438276495399ccdeb58751f1205d38426dbb827969dba299e5a731a[linux-amd64]
• https://www.virustotal.com/gui/file/ace64b3d9dcb47476407938cfc010e888d481da49185c7f392901303d99786ed[linux-arm64]
• https://www.virustotal.com/gui/file/65fb7ccad5d7e83210a788d1fc3e4b9a69c1dbaee2af81ada82fdb0474c26e36[darwin-arm64]
• https://www.virustotal.com/gui/file/c4b0d05b2a4d60bb34d149974779d7115d31f4568dadd4843e6c5b3e275c5c17[windows-amd64]

==== Supply chain Levels for Software Artifacts (SLSA)

This project provides https://slsa.dev[SLSA] (Supply chain Levels for Software Artifacts) provenance for all release binaries. SLSA provenance cryptographically attests that binaries were built from specific source code by a trusted builder.

Two independent proofs are available:

1. SHA256SUMS - Cross-forge reproducibility (same source produces identical binaries on GitLab and GitHub)
2. SLSA provenance - Supply chain attestation (proves binary origin and build process)

===== GitLab (SLSA Level 2)

GitLab releases include SLSA Level 2 provenance via artifacts-metadata.json.

Verification:

[source,bash]

Download binary and SLSA metadata

glab release download -R kambriso/fritzbox-mcp-server
-n 'fritz-mcp-linux-amd64' -n 'artifacts-metadata.json' # <1>

Examine provenance

cat artifacts-metadata.json | jq '.predicateType'

Output: "https://slsa.dev/provenance/v1"

Verify artifact digest matches

sha256sum fritz-mcp-linux-amd64

Compare with digest in artifacts-metadata.json subjects

---

<1> The git tag to verify, e.g., v0.7.7

Alternatively, use the Makefile target:

[source,bash]

make verify-slsa-gitlab-linux-amd64 SLSA_TAG=

The provenance includes:

• In-toto statement format (https://in-toto.io/Statement/v0.1)
• SLSA v1 predicate with build definition
• SHA256 digests for all artifacts
• GitLab CI environment parameters

===== GitHub (SLSA Level 3)

GitHub releases include SLSA Level 3 provenance via the https://github.com/slsa-framework/slsa-github-generator[slsa-github-generator].

Verification using slsa-verifier:

[source,bash]

Download binary and provenance

gh release download -R kambriso/fritzbox-mcp-server
-p 'fritz-mcp-linux-amd64' -p '*.intoto.jsonl'

Verify provenance

go run github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest
verify-artifact fritz-mcp-linux-amd64
--provenance-path multiple.intoto.jsonl
--source-uri github.com/kambriso/fritzbox-mcp-server
--source-tag # <1>

<1> The git tag to verify, e.g., v0.7.7

Alternatively, use the Makefile target:

[source,bash]

make verify-slsa-github-linux-amd64 SLSA_TAG=

===== Cosign Signature Verification

All binaries are signed using https://docs.sigstore.dev/cosign/[Cosign] with keyless signing (OIDC). Signatures and certificates are included in the release artifacts.

[source,bash]

Download binary, signature, and certificate

(from GitLab artifacts or GitHub release)

Verify signature

cosign verify-blob
--signature fritz-mcp-linux-amd64.sig
--certificate fritz-mcp-linux-amd64.pem
--certificate-oidc-issuer https://gitlab.com
fritz-mcp-linux-amd64

===== Independent Verification

All verification can be performed offline using standard tools:

[source,bash]

1. Verify checksums match across forges

diff <(curl -sL gitlab-SHA256SUMS) <(curl -sL github-SHA256SUMS)

2. Verify binary matches checksum

sha256sum -c SHA256SUMS

3. Verify SLSA provenance (slsa-verifier or manual inspection)

4. Verify cosign signature (requires network for certificate chain)

Full trust chain: source code -> CI build -> signed artifact -> your machine

---

==== Cross-Git-Forge Verification

This project publishes identical releases on both GitLab and GitHub. Cross-forge verification proves that neither forge has been compromised - if an attacker modified binaries on one forge, the checksums would not match.

This is independent of SLSA: while SLSA proves "this binary came from this source", cross-forge verification proves "both forges serve the same binary".

[source,bash]

Download checksums from both forges

curl -sL "https://gitlab.com/.../SHA256SUMS" -o gitlab-SHA256SUMS curl -sL "https://github.com/.../SHA256SUMS" -o github-SHA256SUMS

Compare - must be identical

diff gitlab-SHA256SUMS github-SHA256SUMS && echo "Cross-forge verification passed"

Or using CLI tools:

gh release download -R kambriso/fritzbox-mcp-server -p 'SHA256SUMS' -D github glab release download -R kambriso/fritzbox-mcp-server -n 'SHA256SUMS' -D gitlab diff github/SHA256SUMS gitlab/SHA256SUMS

Why this matters:

• Protects against single-forge compromise
• Validates reproducible builds work correctly
• No trust in any single platform required
• Users can verify with standard tools (curl, diff, sha256sum)

=== Token Usage Considerations

This MCP server exposes 143 tools to the AI assistant. Each tool definition (name, description, JSON schema) is sent with every message.

==== Impact on Claude Code / Claude API

• Token overhead: ~25,000-30,000 tokens per message just for tool definitions
• Cost estimate: ~$0.08/message (Sonnet) or ~$0.45/message (Opus) in tool overhead
• Context usage: Tool schemas consume context window space that could be used for conversation

==== Recommendations

===== For occasional use Disable the server when not needed:

[source,bash]

In Claude Code, disable the MCP server:

claude --mcp-server fritzbox=off

Or remove from mcpServers in ~/.claude.json

---

===== For frequent use Consider enabling only for specific projects that need router access, rather than globally.

===== For local LLMs If using this with local models (llama.cpp, Ollama), 143 tools may overwhelm smaller models. Use tool filtering to expose only needed tools.

[TIP]

After the first message in a session, Claude's prompt caching reduces the token cost for subsequent messages. The overhead is most significant for short conversations.

== Developer Guide

=== Architecture

This server is runtime-driven and model-agnostic:

• No hardcoded service structures
• Discovers capabilities dynamically from your FRITZ!Box's service descriptors
• Works with firmware updates automatically
• Supports all FRITZ!Box models (tested with 7490, 7590)

=== MCP SDK Choice

This project uses the community MCP SDK (https://github.com/mark3labs/mcp-go[mark3labs/mcp-go] v0.7.0) instead of the official SDK (modelcontextprotocol/go-sdk) due to compatibility issues:

• Official SDK issues: Tools fail to appear in MCP clients despite proper registration ** https://github.com/modelcontextprotocol/go-sdk/issues/395[Issue #395]: Initialization race conditions and client timeouts ** https://github.com/modelcontextprotocol/go-sdk/issues/200[Issue #200]: Schema generation issues with pointer types (fixed in PR #338)
• Community SDK: Battle-tested, no known compatibility issues
• API incompatibility: The two SDKs are not API-compatible (see https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md[official SDK design doc])

The official SDK uses a different JSON-RPC implementation and lower-level transport interface. While both SDKs work standalone, the community SDK has proven more reliable for stdio transport with Claude Code clients.

=== Development Setup

==== Prerequisites

• Go 1.25 or later
• A FRITZ!Box router on your local network for testing
• FRITZ!Box username and password

==== Clone and Build

[source,bash]

git clone git@github.com:kambriso/fritz-mcp.git cd fritz-mcp make help # See available build targets

==== Configuration

Create .env file with your FRITZ!Box credentials:

[source,bash]

cp .env.example .env

Edit with your credentials

editor .env

Required variables: [source,bash]

FRITZ_HOST=fritz.box # FRITZ!Box hostname or IP FRITZ_PORT=49000 # Service port (default: 49000) FRITZ_USERNAME=your-username # FRITZ!Box username FRITZ_PASSWORD=your-password # FRITZ!Box password

==== FRITZ!Box User Permissions

The user account must have FRITZ!Box-Einstellungen permission enabled:

• German: "Der Benutzer kann alle Einstellungen der FRITZ!Box sehen und bearbeiten"
• English: "The user can view and edit all FRITZ!Box settings"

Configure in FRITZ!Box web UI:

System → FRITZ!Box-Benutzer → [Your User] → Berechtigungen

Enable the checkbox for "FRITZ!Box-Einstellungen".

=== Building

==== Development Build

[source,bash]

make build ./fritz-mcp

==== Production Builds

Build for all supported platforms:

[source,bash]

make dists

This creates binaries in dist/ for:

• Linux (amd64, arm64, 386, arm)
• macOS (amd64, arm64)
• Windows (amd64, arm64)
• WASI (wasm) - WebAssembly with limited functionality

==== WASI Build Notes

A WASI (WebAssembly System Interface) build is included to demonstrate code portability. However, Go's wasip1 target has significant limitations for network applications:

• No network access - Go only supports WASI Preview 1, which lacks socket APIs
• Restricted file system access
• Provides capability-based security sandbox

NOTE: While WasmEdge supports sockets and WASI Preview 2 includes wasi-sockets, Go currently only targets wasip1 (sealed without networking). WASI Preview 2 launched in January 2024, but Go has no announced timeline for GOOS=wasip2 support (tracked in https://github.com/golang/go/issues/65333[Issue #65333]). Go 1.24 (Feb 2025) and Go 1.25 (Aug 2025) do not include wasip2.

Recommendation: Use native binaries or multi-arch containers for production. The WASI build demonstrates WebAssembly portability but cannot function as a network service with current Go releases.

Build for specific platform:

[source,bash]

GOOS=linux GOARCH=amd64 make dist GOOS=darwin GOARCH=arm64 make dist GOOS=windows GOARCH=amd64 make dist

==== Reproducible Builds

All release binaries are reproducible: building from the same source code produces byte-for-byte identical binaries. This allows independent verification that published binaries match the source code.

===== Why Reproducibility Matters

Reproducible builds enable:

• Independent verification of release artifacts
• Detection of supply chain tampering
• Confidence that binaries match reviewed source code
• Foundation for SLSA attestations

===== Build Flags for Reproducibility

The Makefile uses these flags to ensure deterministic builds:

[source,bash]

-trimpath # Remove absolute paths -buildvcs=false # Disable VCS info embedding -buildid= # Clear build ID SOURCE_DATE_EPOCH=$(git) # Use commit timestamp

===== Toolchain Requirements

Go produces reproducible binaries when using the same toolchain distribution. However, different Go distributions (upstream vs Fedora/Debian packages) may produce different binaries due to distribution-specific patches or build experiments.

Known differences:

• Fedora Go 1.25.6 includes GOEXPERIMENT=nodwarf5 compiled into the toolchain
• Upstream Go 1.25.6 (from go.dev or golang:1.25 container) has no experiments
• These differences are embedded in the .go.buildinfo section

===== Verifying Local Builds

To reproduce GitLab CI builds locally, use the same golang:1.25 container:

[source,bash]

Build all platforms in container (matches CI environment)

make dists-container

Compare with published release checksums

sha256sum -c SHA256SUMS

The golang:1.25 Docker image matches the upstream Go distribution, ensuring reproducibility across environments.

===== CI/CD Reproducibility

Both GitLab CI and GitHub Actions use the official Go 1.25 toolchain: GitLab via the golang:1.25 container image, GitHub via actions/setup-go which downloads from go.dev. Both produce byte-for-byte identical binaries. Local builds using distribution-provided Go packages (Fedora, Ubuntu, etc.) may produce different binaries due to distro-specific patches.

For byte-for-byte reproducible local builds, use make dists-container which builds in the golang:1.25 container.

=== Testing

==== Unit Tests

[source,bash]

go test -v ./...

==== Automated Tests & Benchmarks

The project includes a comprehensive test suite and a performance benchmark.

[source,bash]

Run all tests

go test -v ./...

Run the discovery benchmark

go test -v -bench=. .

=== Development Workflow

1. Make changes to source code
2. Run tests: go test -v ./...
3. Build: make build
4. Test locally with your FRITZ!Box
5. Build distributable binaries: make dist

=== Release Process

Releases are automatically published to the public repository when a version tag is pushed.

==== Setup

The PUBLIC_REPO_TOKEN secret is configured and ready for releases.

==== Creating a Release

[source,bash]

Ensure all tests pass

make check

Tag the release (use semantic versioning)

git tag v1.0.0

Push the tag to trigger the release workflow

git push origin v1.0.0

The GitHub Actions workflows will:

Release workflow (link:.github/workflows/release.yml[release.yml]):: . Build binaries for all platforms (Linux, macOS, Windows, WASI) . Generate SHA256 checksums . Create a release in https://github.com/kambriso/fritzbox-mcp-server . Upload all binaries and checksums

Container workflow (link:.github/workflows/container.yml[container.yml]):: . Build WASI container image (tagged with -wasi suffix) . Build multi-arch container (linux/amd64, linux/arm64) . Publish to ghcr.io/kambriso/fritzbox-mcp-server

NOTE: Use the multi-arch container for production. The WASI container demonstrates portability but Go's wasip1 target lacks network support (pending wasip2 support in future Go versions).

==== Supported Release Platforms

Binaries::

• Linux: amd64, arm64, 386, arm
• macOS: amd64 (Intel), arm64 (Apple Silicon)
• Windows: amd64, arm64
• WASI: wasm (Go wasip1 - no network support until wasip2)

Container Images::

• Multi-arch: linux/amd64, linux/arm64 (recommended for production)
• WASI: wasm (portability demo - Go wasip1 lacks network APIs)

== Support

Issues:: https://github.com/kambriso/fritzbox-mcp-server/issues Source Code:: https://github.com/kambriso/fritz-mcp (private)

== License

Source-available. Free for exactly one FRITZ!Box credential pair. Anything else requires a commercial license.

See link:LICENSE.txt[LICENSE.txt] for complete terms.

== Contributing

Contributions are welcome. By submitting a pull request, you agree to the link:CONTRIBUTING.adoc[Contributor License Agreement].

[CAUTION]

This software is provided as-is. Secure your FRITZ!Box with a strong password and ensure it's not exposed to the internet.

'''

FRITZ!Box is a registered trademark of FRITZ! GmbH (formerly AVM GmbH). This project is not affiliated with, endorsed by, or sponsored by FRITZ! GmbH.