mcp-tahoma

An MCP server for a Somfy TaHoma box, built from the local API's OpenAPI descriptor (src/mcp_tahoma/tahoma-openapi.yml) with FastMCP.

Everything happens on your local network: the server talks to the box directly, no Somfy cloud involved.

1. Enable developer mode and get a token

In the TaHoma by Somfy app: Configure the installation → Access the parameters of your box → tap 7 times on the gateway PIN (e.g. 2001-1234-5678) to reveal Developer Mode, then generate a token.

A token is only readable at creation time, so save it right away.

Related MCP server: Homey-Wan-Kenobi-MCP

2. Configure

Copy .env.example to .env and fill in the token:

cp .env.example .env

3. Check that it works

uv run mcp-tahoma --discover   # list the boxes visible on this network
uv run mcp-tahoma --check      # connect, verify the token, list your devices

--check prints something like:

Gateway  : 2001-1234-5678 (mDNS hostname)
Base URL : https://gateway-2001-1234-5678.local:8443/enduser-mobile-web/1/enduserAPI
TLS      : certificate verified, hostname verified
API      : 2022.1.3-1
Token    : accepted, 12 device(s)
  - Living room shutter	io://2001-1234-5678/12345678
  ...

4. Plug it into an MCP client

Claude Code:

claude mcp add tahoma --env TAHOMA_TOKEN=<your-token> -- uv run --directory /path/to/mcp-tahoma mcp-tahoma

Or, in a client that reads a JSON config:

{
  "mcpServers": {
    "tahoma": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-tahoma", "mcp-tahoma"],
      "env": { "TAHOMA_TOKEN": "<your-token>" }
    }
  }
}

The server speaks stdio by default; --transport http --port 8765 serves HTTP instead.

Tools

One tool per local API operation, generated from tahoma-openapi.yml:

Plus two local helpers: gateway_connection_info (which box, which URL, TLS status) and discover_local_gateways (mDNS browse).

Closing a shutter, for instance, is a single execute_actions call:

{
  "label": "close the living room",
  "actions": [
    {
      "deviceURL": "io://2001-1234-5678/12345678",
      "commands": [{ "name": "setClosure", "parameters": [100] }]
    }
  ]
}

The commands a device accepts are listed in its definition.commands, returned by get_devices.

How the box is found

1. TAHOMA_HOST if set;

2. otherwise gateway-<TAHOMA_PIN>.local when TAHOMA_PIN is set and resolves;

3. otherwise an mDNS browse for _kizboxdev._tcp, matching the gateway_pin TXT record — via python-zeroconf, falling back to dns-sd (on macOS the system mDNS daemon regularly sees the box when python-zeroconf does not).

If the gateway is reached by name, the connection is fully verified; if only an IP address is available, the certificate chain is still verified but the hostname cannot be.

TLS

The box serves a certificate signed by the self-signed Overkiz authority, so src/mcp_tahoma/certs/overkiz-root-ca-2048.crt (from https://ca.overkiz.com/overkiz-root-ca-2048.crt) is bundled and trusted for this connection only — the system trust store is untouched.

TAHOMA_VERIFY_SSL=false disables verification entirely. It is a last resort: the traffic stays encrypted but nothing proves you are talking to your box.

Rate limits

There is no rate limiting on the local API, but the gateway is a small device. Call get_setup once at start, then register_event_listener and poll fetch_events at most once per second, rather than polling get_devices. Listeners are destroyed after 10 minutes of inactivity or when the box reboots.

Development

uv sync
uv run pytest

The tests cover the generated tools, discovery parsing and the TLS behaviour against a throwaway HTTPS server presenting a gateway-like certificate; no real box is needed.

src/mcp_tahoma/tahoma-openapi.yml is a symlink to the descriptor at the repository root, so the spec has a single source of truth and still ships inside the wheel.

References

• Somfy TaHoma Developer Mode (vendored in Somfy-TaHoma-Developer-Mode-main/)