Skip to main content
Glama
ghbalf

mcp-fritzbox

by ghbalf
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: flamerobin-mcp-server

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

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ghbalf/mcp-fritzbox'

If you have feedback or need assistance with the MCP directory API, please join our Discord server