使用说明

Symcon MCP服务器🏠

将AI助手连接到 IP Symcon 通过模型上下文协议（MCP）。

将Symcon JSON-RPC API作为MCP工具进行展示，以便AI助手（Claude、Cursor、VS Code Copilot等）可以读取和控制您的智能家居。

[！重要] Symcon JSON-RPC API 需要身份验证。您必须同时提供这两项 SYMCON_API_USER （您的许可证电子邮件）和 SYMCON_API_PASSWORD.

概述

模式	运输	何时使用
本地（Node.js）	stdio	开发，无Docker
Docker/Remote	HTTP或HTTPS	网络上的不同主机

环境变量

变量	默认值	描述
`MCP_PORT`	`4096`	服务器监听的端口
`MCP_HOST_PORT`	`4096`	Docker主机端口
`MCP_TRANSPORT`	`streamable`	`streamable`, `sse`，或 `stdio`
`MCP_AUTH_TOKEN`	（空）	持票人代币；如何创建？
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`
`SYMCON_API_URL`	`http://host.docker.internal:3777/api/`	Symcon JSON-RPC端点
`SYMCON_API_USER`	（空）	Symcon许可证用户名（必填）
`SYMCON_API_PASSWORD`	（空）	Symcon密码（必填）
`SYMCON_TLS_VERIFY`	`true`	设置 `false` 用于自签名证书

Docker 中心

该镜像可在Docker Hub上找到：

docker pull tommi2day/symcon-mcp-server:latest

从Hub快速启动（HTTP）

docker run -d --name symcon-mcp-server \
  -p 4096:4096 \
  -e SYMCON_API_URL=http://192.168.1.100:3777/api/ \
  -e SYMCON_API_USER=your-license-email@example.com \
  -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/
      - SYMCON_API_USER=your-license-email@example.com
      - SYMCON_API_PASSWORD=your-symcon-password
      - MCP_AUTH_TOKEN=my-secret-token

令牌身份验证

当将MCP服务器作为HTTP/SSE服务运行时，建议设置强 MCP_AUTH_TOKEN 以防止未经授权访问您的Symcon实例。

自动创建

如果您使用提供的 ./scripts/run.sh 要启动服务器，它将在第一次运行时自动为您生成一个强大的32字节十六进制令牌，并将其保存到一个名为 auth_token 在项目根中。

手动创建

您可以使用手动生成安全令牌 openssl （可在Linux、macOS和Windows版Git Bash上使用）：

openssl rand -hex 32

然后，将此值设置为 MCP_AUTH_TOKEN 您的环境变量 .env 文件或 docker run 命令。

用法

启用身份验证后，对MCP服务器的所有请求都必须包含以下标头：

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

1·本地（stdio）

集 MCP_TRANSPORT=stdio 并通过Node.js或Docker运行。

克劳德桌面(`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": "your-license-email@example.com",
        "SYMCON_API_PASSWORD": "your-symcon-password"
      }
    }
  }
}

2·Docker（HTTP/SSE）

此模式将MCP服务器作为独立容器运行，为任何兼容的客户端公开HTTP端点。

使用Docker运行

如果您在其他地方运行Symcon实例，请只运行MCP服务器：

docker run -d --name symcon-mcp-server \
  -p 4096:4096 \
  -e SYMCON_API_URL=http://192.168.1.100:3777/api/ \
  -e SYMCON_API_USER=your-license-email@example.com \
  -e SYMCON_API_PASSWORD=your-symcon-password \
  -e MCP_AUTH_TOKEN=my-secret-token \
  tommi2day/symcon-mcp-server:latest

访问方式 `mcp.json`

要从MCP客户端（如Cursor或VS Code）使用服务器，请将其添加到您的 mcp.json 配置：

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

克劳德桌面(`claude_desktop_config.json`)--HTTP/远程

[！警告] Claude Desktop仅支持非本地（远程）MCP服务器的HTTPS。 如果您的服务器在纯HTTP上运行，但未在 localhost，Claude Desktop将拒绝连接。使用以下选项之一：

选项A——首选： 将服务器置于具有有效TLS证书的反向代理（Traefik、nginx、Caddy）后面，并使用 https:// 在URL中。

选项B——快速解决方法： 使用 mcp-remote 作为当地的stdio桥梁。它在您的计算机上运行，并将请求转发到HTTP服务器，因此Claude Desktop将其视为stdio工具。

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

验证MCP端点

健康检查：

curl http://localhost:4096/health

MCP初始化握手 （检查服务器是否响应MCP请求）：

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"}}}'

交互式浏览器用户界面 通过 MCP检查员:

# 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"

检查器打开一个浏览器UI，您可以在其中列出工具、单独调用它们并检查响应。

3·Docker Compose（全栈）

如果你想同时运行这两个程序，请使用此选项 IP Symcon 和那个 MCP 服务器 在单个堆栈中一起（例如用于测试或评估）。

克隆和配置
```
git clone https://github.com/tommi2day/symcon-mcp-server.git
cd symcon-mcp-server
cp .env.example .env
```
编辑 .env 并设置 SYMCON_API_URL, SYMCON_API_USER, SYMCON_API_PASSWORD，以及 MCP_AUTH_TOKEN.

开始

# Starts both services
docker compose up -d

验证
```
curl http://localhost:4096/health
```
访问Symcon图形用户界面 打开 http://localhost:3777 在浏览器中访问IP Symcon控制台。

建筑学

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/

可用的MCP工具

工具	说明
`symcon_get_value`	读取变量的当前值
`symcon_set_value`	将值直接写入变量
`symcon_request_action`	触发设备操作（用于真实设备）
`symcon_get_variable`	获取变量元数据（类型、配置文件、时间戳）
`symcon_get_object`	获取任何对象（类别、实例等）的元数据
`symcon_get_children`	列出子对象ID（0=根）
`symcon_get_object_id_by_name`	按名称查找对象ID
`symcon_get_variable_by_path`	通过斜线分隔的路径解析变量
`symcon_snapshot_variables`	快照根下的所有变量值
`symcon_diff_variables`	检测自上次快照以来的更改
`symcon_run_script`	按ID执行现有Symcon脚本
`symcon_run_script_text`	在Symcon中执行任意PHP代码
`symcon_run_script_text_ex`	执行PHP并将结构化输出、返回值和错误作为单独的字段返回；输出以字节为上限
`symcon_get_script_content`	读取现有脚本的PHP源代码（只读，不执行）
`symcon_script_create`	在Symcon中创建新的PHP脚本
`symcon_script_set_content`	更新现有脚本的PHP内容
`symcon_script_delete`	按ID删除脚本

设备控制提示

开关和继电器

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

飞利浦秀亮度

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

查找变量ID

问AI助手：

“查找我客厅灯的对象ID”

快照和差异（设备发现）

AI呼叫 symcon_snapshot_variables 在相关房间
AI问： 请切换要分配的设备，然后告诉我
用户切换设备
AI呼叫 symcon_diff_variables 确定哪个变量发生了变化

端点

端点	方法	描述
`/`	GET	服务器信息和可用端点
`/health`	GET	健康检查（Symcon状态、正常运行时间、版本）
`/info`	GET	详细的服务器配置和Symcon版本
`/mcp`	POST/GET/DELETE	MCP可流式HTTP传输
`/sse`	GET	MCP SSE传输（如果 `MCP_TRANSPORT=sse`)
`/messages`	POST	SSE消息处理程序
标准	N/A	MCP标准传输（如果 `MCP_TRANSPORT=stdio`)

开发与测试

在本地运行测试

# 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

使用Docker脚本

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

测试架构

测试套件	文件	依赖关系
单位：SymconClient	`tests/symcon-client.test.ts`	MockSymconServer（进程内）
单位：MCP工具	`tests/tools.test.ts`	模拟SymconServer+内存传输
单位：HTTP服务器	`tests/http-server.test.ts`	MockSymconServer+衍生的Express
单位：信息端点	`tests/info.test.ts`	模拟SymconServer+衍生Express（身份验证、掩码和Symcon版本）
集成	`tests/integration.test.ts`	真实 `symcon/symcon-server` Docker容器

CI/CD

该存储库使用两个主要的GitHub Actions工作流：

CI (ci.yml) –在每次推送和拉取请求时运行：

棉绒：ESLint检查。
测试：节点24上的单元测试。
覆盖：单元测试覆盖率计算。
集成测试：对真实的Symcon Docker服务容器运行集成测试。
报告：将覆盖率结果上传到Codecov。

Release (release.yml) –由semver标签或手动调度触发：

凹凸版本 （仅限手册）：更新 package.json 和 openapi.yaml、承诺并推动 main.
棉绒与测试：运行lint、带覆盖率的单元测试和集成测试。
构建和推送：多拱形Docker构建并推送到Docker Hub(tommi2day/symcon-mcp-server).
创建发布：创建一个GitHub标签（如果手动）和一个带有自动生成注释的GitHub版本。

生产检查表

[]设置一个强大的 MCP_AUTH_TOKEN
[]通过防火墙限制端口4096或仅通过反向代理公开
[]在生产中通过反向代理（Traefik、nginx、Caddy）使用HTTPS
[]检查 /health 从您的监控系统

许可证

麻省理工学院