FRITZ!Box MCP Server

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

🇩🇪 Deutsche Version | Comparison with Other Solutions | Changelog

Table of Contents

• 1. Introduction
  • 1.1. What is this?
  • 1.2. How it works (Security Architecture)
  • 1.3. Why use this?
• 2. User Guide
  • 2.1. Quick Start
    • 2.1.1. 1. Installation
    • 2.1.2. 2. Interactive Setup
    • 2.1.3. 3. FRITZ!Box User Permissions
    • 2.1.4. 4. Configure Claude Desktop (or similar/ analog for your preferred AI assistant)
  • 2.2. What can you do?
    • 2.2.1. Ask Questions
    • 2.2.2. Analyze Your Network
    • 2.2.3. Manage Devices
    • 2.2.4. Parental Controls & Scheduling
    • 2.2.5. Troubleshooting
  • 2.3. Examples
    • 2.3.1. Network Health Check
    • 2.3.2. Device Inventory
    • 2.3.3. Time-Delayed Actions
  • 2.4. Troubleshooting
    • 2.4.1. Cannot connect to FRITZ!Box
    • 2.4.2. Claude Desktop doesn’t see the server
    • 2.4.3. Permission errors
  • 2.5. Privacy & Security
    • 2.5.1. Binary Verification
    • 2.5.2. Supply chain Levels for Software Artifacts (SLSA)
    • 2.5.3. Cross-Git-Forge Verification
  • 2.6. Token Usage Considerations
    • 2.6.1. Impact on Claude Code / Claude API
    • 2.6.2. Recommendations
• 3. Developer Guide
  • 3.1. Architecture
  • 3.2. MCP SDK Choice
  • 3.3. Development Setup
    • 3.3.1. Prerequisites
    • 3.3.2. Clone and Build
    • 3.3.3. Configuration
    • 3.3.4. FRITZ!Box User Permissions
  • 3.4. Building
    • 3.4.1. Development Build
    • 3.4.2. Production Builds
    • 3.4.3. WASI Build Notes
    • 3.4.4. Reproducible Builds
  • 3.5. Testing
    • 3.5.1. Unit Tests
    • 3.5.2. Automated Tests & Benchmarks
  • 3.6. Development Workflow
  • 3.7. Release Process
    • 3.7.1. Setup
    • 3.7.2. Creating a Release
    • 3.7.3. Supported Release Platforms
• 4. Support
• 5. License
• 6. Contributing

1. Introduction

1.1. 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.

1.2. How it works (Security Architecture)

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

1.3. 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.

2. User Guide

2.1. Quick Start

2.1.1. 1. Installation

Automated Installation (Linux/macOS - Recommended)

Download and install with automatic checksum verification:

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: # Install specific version FRITZBOX_MCP_VERSION=<tag> 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 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):

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

Windows: Extract the ZIP file.

2.1.2. 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.

./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).

2.1.3. 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")

2.1.4. 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:

{
  "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.

2.2. What can you do?

2.2.1. 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?"

2.2.2. 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:

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.

2.2.3. 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"

2.2.4. 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"

2.2.5. Troubleshooting

"Why is my internet slow?"

"Check if there are any connection problems"

"Show me recent disconnections"

2.3. Examples

2.3.1. 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

2.3.2. 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

2.3.3. 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.

2.4. Troubleshooting

2.4.1. Cannot connect to FRITZ!Box

Check that your router is reachable:

ping fritz.box

Verify credentials in .env file.

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

2.4.2. 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.

2.4.3. Permission errors

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

2.5. 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.

2.5.1. Binary Verification

Independent VirusTotal scans confirm the binaries are clean:

• linux-amd64

• linux-arm64

• darwin-arm64

• windows-amd64

2.5.2. Supply chain Levels for Software Artifacts (SLSA)

This project provides 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:

# Download binary and SLSA metadata
glab release download <tag> -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:

make verify-slsa-gitlab-linux-amd64 SLSA_TAG=<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 slsa-github-generator.

Verification using slsa-verifier:

# Download binary and provenance
gh release download <tag> -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 <tag> # (1)

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

Alternatively, use the Makefile target:

make verify-slsa-github-linux-amd64 SLSA_TAG=<tag>

Cosign Signature Verification

All binaries are signed using Cosign with keyless signing (OIDC). Signatures and certificates are included in the release artifacts.

# 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:

# 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

2.5.3. 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".

# 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 <tag> -R kambriso/fritzbox-mcp-server -p 'SHA256SUMS' -D github
glab release download <tag> -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)

2.6. 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.

2.6.1. 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

2.6.2. Recommendations

For occasional use

Disable the server when not needed:

# 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.

3. Developer Guide

3.1. 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)

3.2. MCP SDK Choice

This project uses the community MCP SDK (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

  • Issue #395: Initialization race conditions and client timeouts

  • 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 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.

3.3. Development Setup

3.3.1. Prerequisites

• Go 1.25 or later

• A FRITZ!Box router on your local network for testing

• FRITZ!Box username and password

3.3.2. Clone and Build

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

3.3.3. Configuration

Create .env file with your FRITZ!Box credentials:

cp .env.example .env
# Edit with your credentials
editor .env

Required variables:

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

3.3.4. 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".

3.4. Building

3.4.1. Development Build

make build
./fritz-mcp

3.4.2. Production Builds

Build for all supported platforms:

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

3.4.3. 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 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:

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

3.4.4. 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:

-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:

# 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.

3.5. Testing

3.5.1. Unit Tests

go test -v ./...

3.5.2. Automated Tests & Benchmarks

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

# Run all tests
go test -v ./...

# Run the discovery benchmark
go test -v -bench=. .

3.6. 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

3.7. Release Process

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

3.7.1. Setup

The PUBLIC_REPO_TOKEN secret is configured and ready for releases.

3.7.2. Creating a Release

# 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 (release.yml)

1. Build binaries for all platforms (Linux, macOS, Windows, WASI)

2. Generate SHA256 checksums

3. Create a release in https://github.com/kambriso/fritzbox-mcp-server

4. Upload all binaries and checksums

Container workflow (container.yml)

1. Build WASI container image (tagged with -wasi suffix)

2. Build multi-arch container (linux/amd64, linux/arm64)

3. 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).

3.7.3. 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)

4. Support

Issues

https://github.com/kambriso/fritzbox-mcp-server/issues

Source Code

https://github.com/kambriso/fritz-mcp (private)

5. License

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

See LICENSE.txt for complete terms.

6. Contributing

Contributions are welcome. By submitting a pull request, you agree to the 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.