freebox-mcp

A spec-driven Model Context Protocol server for the Freebox OS API — exposing the entire local API of your Freebox Server to any MCP client (Claude, etc.) as ready-to-call tools.

Every tool is generated from an OpenAPI 3.1 document that is itself auto-generated from the official Freebox documentation (https://dev.freebox.fr/sdk/os/). When Free ships a new API version, a weekly job regenerates the spec and ships a release — no hand-written tool code to maintain.

 official docs (Sphinx)
        │  scrape + parse objects.inv & httpdomain/jsondomain HTML   (deterministic, pure Python)
        ▼
 spec/freebox-openapi.json  ──►  FastMCP.from_openapi  ──►  ~230 MCP tools
        ▲                                   ▲
 spec/overrides.json (committed)     authenticated httpx client
 (one-time AI audit, static data)    (discovery · HMAC session · TLS · envelope unwrap)

• Exhaustive — 220 documented operations across 29 sections (wifi, lan, connection, calls, contacts, downloads, fs, nat, dhcp, vpn server + client, pvr, parental control, airmedia, system, …) ⇒ ~230 MCP tools.

• Self-maintaining — the spec regenerates from the docs deterministically; CI does it weekly and auto-releases on change.

• Secure — app-token never leaves your machine, HMAC-SHA1 sessions, TLS verified against the bundled Freebox root CAs, 0600 credential store. See SECURITY.md.

Quick start

# 1. Authorize the app on your Freebox (one time — press the button on the box).
uvx freebox-mcp authorize

# 2. Point your MCP client at it (stdio).
uvx freebox-mcp

authorize is a one-time physical confirmation (Freebox anti-hijack design). After it, the token is saved and every later session opens automatically — you never touch the box again.

MCP client config (Claude Desktop / Claude Code)

{
  "mcpServers": {
    "freebox": { "command": "uvx", "args": ["freebox-mcp"] }
  }
}

Docker

docker run -i --rm -v ~/.config/freebox-mcp:/home/app/.config/freebox-mcp \
  ghcr.io/nelson-proia/freebox-mcp

(The container needs LAN access to the box; on Linux add --network host.)

Run from source, no install

uvx --from git+https://github.com/Nelson-PROIA/freebox-mcp freebox-mcp discover

Related MCP server: Promethean OS MCP

What you can do

Because the whole API is exposed, an LLM can chain real tasks:

• List every device on the LAN, then reboot the box.

• Set up a port-forward / NAT redirect for a self-hosted service.

• Schedule a TV recording on the PVR and manage existing recordings.

• Toggle wifi, change the SSID/passphrase, split 2.4/5 GHz bands.

• Read live xDSL / FTTH line stats (rate, SNR, attenuation).

• Apply per-device parental controls and time schedules.

• Configure the built-in VPN server and provision VPN client tunnels.

• Manage downloads + RSS feeds, FTP, network shares, Freeplug & switch ports.

CLI

freebox-mcp                 run the MCP server over stdio (default)
freebox-mcp --http          run over streamable-HTTP (--host/--port)
freebox-mcp authorize       register the app (press the button on the box)
freebox-mcp login           open a session and print granted permissions
freebox-mcp discover        print discovery info and the chosen transport
freebox-mcp tools           list the generated MCP tools
freebox-mcp call OP [JSON]  invoke one operation, e.g. `freebox-mcp call get_system`

Configuration

Scoping the sections keeps the tool surface small when you only care about a few areas.

Permissions. Configuration-changing tools need the settings permission. Grant it (and parental, etc.) for this app in the Freebox OS web UI: Paramètres ▸ Gestion des accès ▸ Applications — no walking to the box.

Regenerating the spec

python -m tools.build            # scrape live docs → parse → emit spec/freebox-openapi.json
python -m tools.build --offline  # rebuild from the committed cache (deterministic; what CI verifies)

The CI regenerate workflow runs this weekly; on any spec change it bumps the version, commits, tags, and releases automatically.

Development

uv sync --group dev
uv run pytest                 # unit + integration (mocked); add FREEBOX_TEST=1 for live
uv run ruff check . && uv run ruff format .

License

MIT — see LICENSE. Not affiliated with Free / Iliad.