mcp-fritzbox

A Model Context Protocol (MCP) server for interfacing with AVM FRITZ!Box routers (FRITZ!OS 8.20+). Control smart home devices, monitor network status, and administer your router through any MCP-compatible client.

Design Architecture

MCP Client (Claude Desktop, Claude Code, etc.)
  │ stdio or HTTP/SSE
MCP Server (server.ts)
  │ routes tool calls
  ├── SmartHomeClient ──→ REST API (/api/v0/smarthome/)
  ├── TR064Client ──────→ SOAP (TR-064 UPnP)
  └── AuthProvider ─────→ SID login (login_sid.lua) + HTTP Digest

Components

Component	File	Responsibility
AuthProvider	src/auth/auth-provider.ts	MD5 challenge-response SID login, HTTP digest credentials for TR-064, lazy re-auth on session expiry
SmartHomeClient	src/client/smart-home.ts	REST calls to the FRITZ!Box Smart Home API for thermostats and switches
TR064Client	src/client/tr064.ts	SOAP calls for router administration (WAN status, bandwidth, guest WiFi, etc.)
HTTP Client	src/client/http.ts	Shared axios instance with 403 interceptor for automatic SID renewal
MCP Server	src/server.ts	Tool registration and error handling — maps MCP tool calls to client methods

Tools

Smart Home

Tool	Arguments	Output
list_devices	none	{ smartHomeDevices: [...], networkDevices: [...] } — combined smart home actors and network hosts
set_thermostat	ain: string, temperature: number | "ON" | "OFF"	Updated thermostat state (target temp, current temp, battery)
toggle_switch	ain: string, state: boolean	Updated switch state with current power reading (mW) and total energy (Wh)
get_device_stats	ain: string	Temperature history or energy consumption statistics

Router Administration (TR-064)

Tool	Arguments	Output
get_system_info	none	{ modelName, firmwareVersion, serialNumber }
get_wan_status	none	{ externalIp, connectionStatus, uptime, lastError }
get_bandwidth_stats	none	{ totalBytesSent, totalBytesReceived, maxBitRateUp, maxBitRateDown }
toggle_guest_wifi	enable: boolean	{ enabled, ssid, securityMode }
get_device_log	count?: number	Array of recent system log lines (default: 20)
reconnect_wan	none	{ message: "WAN reconnect initiated..." } — forces new external IP

Setup Guide

1. Create a FRITZ!Box User

1. Open your FRITZ!Box web UI at http://fritz.box
2. Navigate to System → FRITZ!Box Users → Add User
3. Set a username and password
4. Enable these permissions:
   • Smart Home — required for thermostat/switch control
   • FRITZ!Box Settings — required for TR-064 (WAN status, guest WiFi, etc.)
   • Access from the Internet — only if you need remote access
5. Click Apply

2. Install

From GitHub:

git clone https://github.com/ghbalf/mcp-fritzbox.git
cd mcp-fritzbox
npm install
npm run build

3. Configure

Set environment variables:

export FRITZBOX_HOST=fritz.box       # default, or use IP: 192.168.178.1
export FRITZBOX_USERNAME=your_user
export FRITZBOX_PASSWORD=your_pass

Or pass CLI flags:

node dist/index.js --host 192.168.178.1 --user admin --pass secret

CLI flags override environment variables.

4. Connect to an MCP Client

Claude Code — add a .mcp.json to your project root:

{
  "mcpServers": {
    "fritzbox": {
      "command": "node",
      "args": ["/path/to/mcp-fritzbox/dist/index.js"],
      "env": {
        "FRITZBOX_HOST": "fritz.box",
        "FRITZBOX_USERNAME": "your_user",
        "FRITZBOX_PASSWORD": "your_pass"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "fritzbox": {
      "command": "node",
      "args": ["/path/to/mcp-fritzbox/dist/index.js"],
      "env": {
        "FRITZBOX_HOST": "fritz.box",
        "FRITZBOX_USERNAME": "your_user",
        "FRITZBOX_PASSWORD": "your_pass"
      }
    }
  }
}

HTTP/SSE mode (for remote clients):

node dist/index.js --http --port 3000
# SSE endpoint: http://localhost:3000/sse
# Message endpoint: http://localhost:3000/messages

5. Verify Connection

FRITZBOX_USERNAME=your_user FRITZBOX_PASSWORD=your_pass npm run test:integration

Development

npm run start:dev    # Run with tsx (no build needed)
npm run build        # Compile TypeScript
npm test             # Run unit tests
npm run test:watch   # Watch mode
npm run test:integration  # Live FRITZ!Box connection test

Troubleshooting

Error	Cause	Fix
AUTH_FAILED (SID all zeros)	Wrong username or password	Verify credentials in FRITZ!Box UI under System → FRITZ!Box Users
CONNECTION_FAILED (ECONNREFUSED)	FRITZ!Box unreachable	Check FRITZBOX_HOST — try IP address 192.168.178.1 instead of fritz.box
CONNECTION_FAILED (ETIMEDOUT)	Network issue or wrong port	Ensure you're on the same LAN; check no firewall blocks port 80/49000
403 Forbidden (persistent)	User lacks permissions	Enable "Smart Home" and "FRITZ!Box Settings" in the user's FRITZ!Box permissions
DEVICE_NOT_FOUND	Invalid AIN	Run list_devices first to find valid Actor Identification Numbers
INVALID_PARAMETER (temperature)	Out of range	Temperature must be 8.0–28.0°C, or "ON" / "OFF" for boost/off mode
SOAP fault on guest WiFi	No guest network configured	Set up a guest network in FRITZ!Box UI first (WiFi → Guest Access)
TR-064 401 Unauthorized	Digest auth rejected	User needs "FRITZ!Box Settings" permission; some models require explicit TR-064 access

License

MIT