mcp-overkiz

The mcp-overkiz MCP server exposes a light control system that automatically discovers lights from your Overkiz/Somfy account. Each light is presented as a resource with a name and a current On/Off state, accessible via a custom light:// URI scheme. The server also provides three built-in tools to manage lights: list-lights, which lists all available lights and their current status; light-on, which turns on a light by specifying its name; and light-off, which turns off a light by name. To use these tools, run the server with the configured environment variables so it can authenticate to Overkiz and fetch the lights. Once running, you can invoke the tools through your MCP client (e.g., Claude) by issuing commands like 'List all my lights', 'Turn on the living room light', or 'Turn off the bedroom light'.

Prerequisites:

• Access to an MCP runtime that provides uv/uvx (e.g., Claude Desktop or a local MCP runtime installation).
• Node.js environment is not strictly required for uv/uvx-based setups, but ensure your environment can run the MCP runtime you choose.
• Overkiz/Somfy account credentials to connect to the lights.

Installation steps (example using uvx per the repository's quickstart):

1. Ensure you have uvx installed and available on your PATH. See your MCP runtime provider’s installation instructions.

2. Prepare environment variables for Overkiz authentication:

   • OVERKIZ_USERNAME: your Overkiz/Somfy account email
   • OVERKIZ_PASSWORD: your Overkiz/Somfy account password
   • OVERKIZ_SERVER: the Overkiz server to connect to (default somfy-europe)

3. Run the MCP server using the provided configuration:

   • Quickstart (Claude Desktop style): uvx mcp-overkiz

   • Alternatively, development/local run (directory mode): uv run --directory /path/to/project/folder/mcp-overkiz mcp-overkiz

4. Ensure the server is reachable by your MCP client and authorize it with your Overkiz account if prompted.

5. Verify lights discovery and functionality using the list-lights tool, then try turning specific lights on or off by name.

Notes and tips:

• The server automatically discovers lights from your Overkiz account; ensure your Overkiz credentials have access to the devices you expect to control.
• If you encounter authentication issues, verify that OVERKIZ_USERNAME and OVERKIZ_PASSWORD are correct and that OVERKIZ_SERVER is set (default somfy-europe).
• When running in development mode, you can point the MCP runtime to the local mcp-overkiz project directory so changes are picked up without reinstalling.
• The tool interface uses light names. Use exact device names as shown by the discovery output when issuing light-on/light-off commands.
• If you switch Overkiz servers (e.g., from somfy-europe to another region), update OVERKIZ_SERVER accordingly and restart the MCP server.