tommi2day/symcon-mcp-server repository overview

Deutsche Version des README⁠

⁠Symcon MCP Server 🏠

Connects AI assistants to IP-Symcon⁠ via the Model Context Protocol (MCP).

Exposes the Symcon JSON-RPC API as MCP tools so that AI assistants (Claude, Cursor, VS Code Copilot, …) can read and control your smart home.

⁠Overview

⁠Environment Variables

⁠Docker Hub

The image is available on Docker Hub:

docker pull tommi2day/symcon-mcp-server:latest

⁠Quick start from Hub (HTTP)

docker run -d --name symcon-mcp-server \
  -p 4096:4096 \
  -e SYMCON_API_URL=http://192.168.1.100:3777/api/ \
  -e [email protected] \
  -e SYMCON_API_PASSWORD=your-symcon-password \
  -e MCP_AUTH_TOKEN=my-secret-token \
  tommi2day/symcon-mcp-server:latest

⁠In docker-compose.yml

services:
  symcon-mcp-server:
    image: tommi2day/symcon-mcp-server:latest
    ports:
      - "4096:4096"
    environment:
      - SYMCON_API_URL=http://192.168.1.100:3777/api/
      - [email protected]
      - SYMCON_API_PASSWORD=your-symcon-password
      - MCP_AUTH_TOKEN=my-secret-token

⁠Token Authentication

When running the MCP server as an HTTP/SSE service, it's recommended to set a strong MCP_AUTH_TOKEN to prevent unauthorized access to your Symcon instance.

⁠Automatic creation

If you use the provided ./scripts/run.sh to start the server, it will automatically generate a strong 32-byte hex token for you on the first run and save it to a file named auth_token in the project root.

⁠Manual creation

You can generate a secure token manually using openssl (available on Linux, macOS, and Git Bash for Windows):

openssl rand -hex 32

Then, set this value as the MCP_AUTH_TOKEN environment variable in your .env file or docker run command.

⁠Usage

When authentication is enabled, all requests to the MCP server must include the following header:

Authorization: Bearer <your-mcp-auth-token>

⁠1 · Local (stdio)

Set MCP_TRANSPORT=stdio and run via Node.js or Docker.

⁠Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "symcon": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "tommi2day/symcon-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SYMCON_API_URL": "http://192.168.1.100:3777/api/",
        "SYMCON_API_USER": "[email protected]",
        "SYMCON_API_PASSWORD": "your-symcon-password"
      }
    }
  }
}

⁠2 · Docker (HTTP/SSE)

This mode runs the MCP server as a standalone container, exposing an HTTP endpoint for any compatible client.

⁠Run with Docker

If you have a Symcon instance running elsewhere, run just the MCP server:

docker run -d --name symcon-mcp-server \
  -p 4096:4096 \
  -e SYMCON_API_URL=http://192.168.1.100:3777/api/ \
  -e [email protected] \
  -e SYMCON_API_PASSWORD=your-symcon-password \
  -e MCP_AUTH_TOKEN=my-secret-token \
  tommi2day/symcon-mcp-server:latest

⁠Access with mcp.json

To use the server from an MCP client (like Cursor or VS Code), add it to your mcp.json configuration:

{
  "mcpServers": {
    "symcon": {
      "url": "http://localhost:4096/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    }
  }
}

⁠Claude Desktop (claude_desktop_config.json) — HTTP/Remote

{
  "mcpServers": {
    "symcon": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://192.168.1.100:4096/mcp",
        "--allow-http",
        "--header", "Authorization:Bearer my-secret-token"
      ]
    }
  }
}

⁠Verify the MCP endpoint

Health check:

curl http://localhost:4096/health

MCP initialize handshake (checks that the server responds to MCP requests):

curl -s -X POST http://localhost:4096/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Interactive browser UI via MCP Inspector⁠:

# Local server — direct HTTP
npx @modelcontextprotocol/inspector http://localhost:4096/mcp

# Remote HTTP server — via mcp-remote bridge
npx @modelcontextprotocol/inspector \
  npx mcp-remote http://192.168.1.100:4096/mcp \
  --allow-http \
  --header "Authorization:Bearer my-secret-token"

The inspector opens a browser UI where you can list tools, call them individually, and inspect responses.

⁠3 · Docker Compose (Full Stack)

Use this if you want to run both IP-Symcon and the MCP Server together in a single stack (e.g., for testing or evaluation).

1. Clone and configure

   git clone https://github.com/tommi2day/symcon-mcp-server.git
   cd symcon-mcp-server
   cp .env.example .env
   

   Copy

   Edit .env and set SYMCON_API_URL, SYMCON_API_USER, SYMCON_API_PASSWORD, and MCP_AUTH_TOKEN.

2. Start

   # Starts both services
   docker compose up -d
   

   Copy

3. Verify

   curl http://localhost:4096/health
   

   Copy

4. Access Symcon GUI Open http://localhost:3777⁠ in your browser to access the IP-Symcon console.

⁠Architecture

AI Client (Claude / Cursor / …)
        │  HTTP POST /mcp
        ▼
┌─────────────────────────┐
│   symcon-mcp-server     │  :4096
│   (Docker container)    │
│                         │
│  MCP Tools              │
│   ├─ get_value          │
│   ├─ set_value          │
│   ├─ request_action     │
│   ├─ get_variable       │
│   ├─ get_object         │
│   ├─ get_children       │
│   ├─ get_object_by_name │
│   ├─ get_variable_path  │
│   ├─ snapshot_variables │
│   ├─ diff_variables     │
│   ├─ run_script         │
│   ├─ run_script_text    │
│   ├─ run_script_text_ex │
│   ├─ get_script_content │
│   ├─ script_create      │
│   ├─ script_set_content │
│   └─ script_delete      │
└────────────┬────────────┘
             │ [JSON-RPC](https://www.symcon.de/en/service/documentation/developer-area/data-exchange/)
             ▼
    IP-Symcon  :3777/api/

⁠Available MCP Tools

⁠Device Control Tips

⁠Switches & relays

Use symcon_request_action with value true (on) or false (off)

⁠Philips Hue brightness

Use symcon_request_action with value 0–254 (0 = off, 254 = full brightness)

⁠Finding your variable IDs

Ask the AI assistant:

⁠Snapshot & Diff (device discovery)

1. AI calls symcon_snapshot_variables on the relevant room
2. AI asks: "Please toggle the device you want to assign, then tell me"
3. User toggles the device
4. AI calls symcon_diff_variables to identify which variable changed

⁠Endpoints

⁠Development & Testing

⁠Running tests locally

# Install
npm install

# Unit tests
npm test

# Integration tests (starts a real Symcon Docker container)
npm run test:integration

# All tests
npm run test:all

⁠Using Docker Scripts

./scripts/test.sh                     # unit tests via Docker
./scripts/test.sh --integration       # unit + integration tests
./scripts/lint.sh                     # lint

⁠Test architecture

⁠CI/CD

The repository uses two primary GitHub Actions workflows:

CI (ci.yml) – runs on every push and pull request:

1. Lint: ESLint checks.
2. Test: Unit tests on Node 24.
3. Coverage: Unit test coverage calculation.
4. Integration Tests: Runs integration tests against a real Symcon Docker service container.
5. Report: Uploads coverage results to Codecov.

Release (release.yml) – triggered by a semver tag or manual dispatch:

1. Bump version (Manual only): Updates package.json and openapi.yaml, commits and pushes to main.
2. Lint & Test: Runs lint, unit tests with coverage, and integration tests.
3. Build & Push: Multi-arch Docker build and push to Docker Hub (tommi2day/symcon-mcp-server).
4. Create Release: Creates a GitHub tag (if manual) and a GitHub Release with auto-generated notes.

⁠Production Checklist

• Set a strong MCP_AUTH_TOKEN
• Restrict port 4096 via firewall or only expose via reverse proxy
• Use HTTPS via a reverse proxy (Traefik, nginx, Caddy) in production
• Check /health from your monitoring system

⁠License

MIT