Loxone MCP Server

Loxone MCP 服务器

一个模型上下文协议（MCP）服务器，用于将人工智能助手和集成开发环境（IDE）连接到您的Loxone智能家居系统。您可以通过自然语言或代码来控制灯光、百叶窗、气候以及场景。

它的功能/作用

• 设备控制打开/关闭灯光，调节调光器，控制百叶窗和气候
• 场景管理触发Loxone场景和自动化情景
• 实时更新通过WebSocket进行实时设备状态监控
• 安全访问用于安全设备的PIN码保护命令
• 自动发现自动查找您的所有Loxone设备

要求

• Python 3.10+
• Loxone Miniserver（第一代/第二代，固件版本10.0+）
• 通过网络访问您的Miniserver
• 有效的Miniserver凭据

本地设置

安装 uv（Python 包管理器）

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)  
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装并运行服务器

# Clone and setup
git clone 
cd loxone-mcp-server

# Install dependencies
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Run the server (no configuration needed)
uv run loxone-mcp-server

配置

服务器是 无状态的 并且不需要环境凭证。每个MCP客户端在调用工具时都会提供凭证。

可选服务器配置：

# Optional server settings
MCP_TRANSPORT=http    # Set to 'http' for HTTP mode (default: 'stdio')
MCP_HOST=127.0.0.1    # HTTP host (default: '127.0.0.1')
MCP_PORT=8000         # HTTP port (default: 8000)
LOG_LEVEL=INFO        # Logging level

运行MCP服务器

服务器支持两种传输模式：

1. 标准I/O模式（默认）

对于通过stdio连接的MCP客户端，如Claude Desktop：

# Run with stdio transport (default)
uv run loxone-mcp-server

2. HTTP 模式

对于通过HTTP连接的基于Web的客户端或Amazon Q CLI：

# Run with HTTP transport
MCP_TRANSPORT=http uv run loxone-mcp-server

# Or use the dedicated HTTP command
uv run loxone-mcp-server-http

# Server will be available at: http://127.0.0.1:8000/mcp

Amazon Q CLI MCP 配置

设置 Amazon Q CLI 代理（标准输入输出模式）

该项目包含一个预配置的 Amazon Q CLI 代理：

# Activate the agent (no credentials needed - provided per tool call)
q use agent loxone-smart-home

代理配置位于 .amazonq/cli-agents/loxone-agent.json 并包括：

• MCP服务器设置与 uv 跑步者；赛跑者
• 允许使用的工具以确保安全操作
• 访问文档和配置文件的资源权限

注： 现在，凭据是随每个工具调用提供的，而不是存储在设置中。

设置使用HTTP传输的Amazon Q CLI

要使用支持HTTP传输的Amazon Q CLI，请在一个控制台中运行服务器，并配置Q CLI通过HTTP进行连接：

控制台1 - 启动HTTP服务器：

# Start HTTP server (no credentials needed)
MCP_TRANSPORT=http uv run loxone-mcp-server

# Server will show: "MCP endpoint will be available at: http://127.0.0.1:8000/mcp"

控制台 2 - 配置 Amazon Q CLI：

# Create HTTP-based agent configuration
q agent create loxone-http --mcp-server http://127.0.0.1:8000/mcp

# Or modify existing agent to use HTTP endpoint
q settings set agent.loxone-smart-home.mcp_endpoint http://127.0.0.1:8000/mcp

# Use the agent
q use agent loxone-http

与其他MCP客户端一起使用

Claude Desktop（工作室模式）

添加到您的Claude桌面配置中（~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "loxone": {
      "command": "uv",
      "args": ["--directory", "/path/to/loxone-mcp-server", "run", "loxone-mcp-server"]
    }
  }
}

Claude Desktop（HTTP模式）

对于HTTP模式，请单独启动服务器，并将Claude Desktop配置为通过HTTP连接：

1. 以HTTP模式启动服务器：

MCP_TRANSPORT=http uv run loxone-mcp-server

1. 为Claude Desktop配置HTTP：

{
  "mcpServers": {
    "loxone": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

其他MCP客户端

• 标准I/O模式使用上面所示的命令行模式
• HTTP模式连接到 http://127.0.0.1:8000/mcp 终端节点

可用的MCP工具

服务器为人工智能助手提供了这些工具。 所有工具都需要以迷你服务器凭据作为参数：

• loxone_list_devices - 列出所有设备（需要：主机名、用户名、密码）
• loxone_get_device_state - 获取当前设备状态（需要：主机、用户名、密码、UUID）
• loxone_set_switch - 开启/关闭开关（需要：主机名、用户名、密码、唯一标识符、状态）
• loxone_set_dimmer - 控制灯光亮度（需要：主机、用户名、密码、UUID、亮度）
• loxone_set_cover_position - 控制遮光板/遮罩（需要：主机、用户名、密码、唯一标识符、位置）
• loxone_set_temperature - 设置气候目标温度（需要：主机、用户名、密码、UUID、温度）
• loxone_list_scenes - 列出可用场景（需要：主机名、用户名、密码）
• loxone_trigger_scene - 激活一个场景（需要：主机、用户名、密码、UUID）
• loxone_send_command - 发送原始命令（需要：主机名、用户名、密码、唯一标识符、值）
• loxone_send_secured_command - 通过PIN码保护的命令（需要：主机名、用户名、密码、唯一标识符、值、代码）

示例用法：

• “列出位于192.168.1.100的我的迷你服务器上的设备，用户名为admin，密码为mypass”
• “在迷你服务器192.168.1.100上使用凭据admin/mypass启用设备uuid abc123”

发展

设置开发环境

# Install dependencies
uv pip install -e ".[dev]"

# Setup pre-commit hooks (optional but recommended)
make setup-pre-commit

运行测试和检查

# Run all CI checks locally
make ci-check

# Individual commands
make test          # Run tests with coverage
make lint          # Check code with ruff
make format        # Format code with black
make type-check    # Type check with mypy

使用真实迷你服务器进行测试

# Integration tests now use credentials passed to tools
uv run pytest tests/integration/

测试HTTP传输

# Start server in HTTP mode (no credentials needed)
MCP_TRANSPORT=http uv run loxone-mcp-server

# In another terminal, test the endpoint
curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'

故障排除

常见问题

连接失败

• 检查迷你服务器的IP地址和凭据
• 验证网络连接： ping
• 确保端口80/443可访问

认证失败

• 在Loxone Config中验证用户名/密码
• 删除令牌文件并重启： rm loxone_token.json
• 在Loxone Config中检查用户权限

设备未找到

• 重启服务器以重新加载设备结构
• 在Loxone Config中检查设备UUID
• 确保设备未被隐藏/禁用

调试日志记录

export LOG_LEVEL=DEBUG
uv run loxone-mcp-server

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

相关项目

• 模型上下文协议
• Loxone智能家居
• Home Assistant与Loxone的集成