Proxus Industrial MCP Server

Proxus Industrial MCP Server

让 Claude Desktop、Cursor 和 VS Code 等 AI 助手以只读方式访问工业设备。支持 Modbus TCP 和 OPC UA（Basic256Sha256、Aes128_Sha256_RsaOaep 或 Aes256_Sha256_RsaPss，可使用 Sign 或 SignAndEncrypt，也可不启用安全；支持匿名或用户名登录）。

内容精简自一次针对模拟设备的真实会话（docs/demo.json）。更多信息请见 proxus.io/tools/industrial-mcp-server。

工具

工具	功能
list_devices	已配置的设备、端点、ISA-95 路径和连接状态
read_address	原始寄存器或位：hr:0、ir:10、coil:5、di:0 或 40001
watch_address	在 1–60 s 内轮询 Modbus 地址，并概述其变化；可解码为 uint16、int16、uint32、int32 或 float32，支持任意字节序
decode_registers	以所有常见格式读取最多 16 个寄存器：int16/32、uint、ABCD/CDAB/BADC/DCBA 字节序的 float32，以及两种字序的 float64
browse	OPC UA 节点的子节点（默认：Objects 文件夹）
read_nodes	最多读取 50 个 OPC UA 变量，并提供数据类型、质量、状态码和源时间戳
watch_nodes	通过订阅在 1–60 s 内监视最多 20 个 OPC UA 变量：每次变化，以及首次、最后一次、最小值、最大值和平均值
diagnose_connection	诊断无法访问设备的原因：名称、TCP、协议握手、安全和证书、登录、测试读取、标识和时钟；逐步说明下一步尝试什么
find_device_map	按厂商、型号或别名搜索寄存器映射库，例如 PM5560
get_device_map	获取映射中的寄存器（键、地址、类型、字节序、单位、缩放），可按搜索词筛选
read_named	按键读取设备映射中的寄存器，并返回带单位的工程值
verify_device_map	将设备映射与真实设备核对，并生成硬件验证报告（只读）

无法向设备写入数据。

寄存器映射

借助寄存器映射，助手可以读取 voltage_l1_n，而不必猜测 hr:0-1 是字序交换的浮点数。 映射列出设备型号的所有寄存器：地址、数据类型、字节序、缩放（固定值或 SunSpec 缩放因子寄存器）、单位、枚举值的含义，以及所依据的厂商文档。二进制文件内置了开源的 Modbus Register Maps 集合（能源表、电力分析仪、驱动器、逆变器）；每个版本也会附带 register-maps.json.gz。

在配置中按 ID 或映射 JSON 文件路径，为 Modbus 设备指定映射：

"meter-1": { "protocol": "modbus-tcp", "host": "192.168.10.40", "map": "schneider-electric/pm5500-pm5600-pm5700" }

maps_dir 可从包含 JSON 文件的文件夹中添加映射（或替换具有相同 ID 的内置映射），这些文件由该集合中的 python3 tools/maps.py build 生成。如果映射不存在，服务启动时会停止并说明原因。映射会告诉助手如何读取寄存器，而不会指示其写入：read_named 只会读取。

在设备上验证映射

大多数映射都根据厂商文档转录而来。请让助手验证设备的映射：verify_device_map 会对每个寄存器读取一次（只读），检查数值是否合理（浮点数、频率、电压、功率因数、能量计数器、型号），并请你将两个数值与设备显示值进行比较。结果是一份报告和一个链接，可打开预先填写好的映射集合问题；你可使用自己的 GitHub 账号提交问题，机器人会将你加入该映射的验证名单。未经你同意不会发送任何内容；报告仅包含检查结果，不含地址、主机名或序列号。

OPC UA 安全

为每台设备设置 security_mode（sign_and_encrypt、sign 或 none）和 security_policy（Basic256Sha256、 Aes128_Sha256_RsaOaep 或 Aes256_Sha256_RsaPss）。证书存放在 pki_dir 中（默认位于配置文件旁的 pki/）， 采用大多数 OPC UA 工具使用的目录结构：

文件夹	内容
own/	此服务的应用程序证书，首次使用时创建（私钥仅对你可读）
trusted/	你批准的服务证书
rejected/	已发现但未批准的服务证书

双向信任都不会自动建立：

1. 首次连接时，服务的证书会放入 rejected/，工具会返回其 SHA-256 指纹。向服务管理员确认指纹，然后将文件移至 trusted/。
2. 如果服务返回 BadCertificateUntrusted 或 BadSecurityChecksFailed，说明它尚未信任此客户端。 proxus-mcp certificate --config <file> 会打印要在服务端信任的此服务证书文件及其指纹。

密码绝不会写入配置文件：password_env 用于指定保存密码的环境变量。错误信息会包含 OPC UA StatusCode 名称、规范中的说明以及建议的下一步操作。

安装

从 releases 页面下载适用于你平台的归档文件并解压，然后将 MCP 客户端指向 proxus-mcp 二进制文件（见下文的 Claude Desktop）。每个归档文件旁都有一个 .sha256 文件。二进制文件目前尚未经过代码签名：在 macOS 上解压后运行一次 xattr -d com.apple.quarantine proxus-mcp，在 Windows 上首次运行时选择“更多信息，仍要运行”。

proxus-mcp --version 会显示版本。

Docker

docker run -i --rm -v "$PWD:/config" ghcr.io/proxus-io/proxus-mcp:<version>

镜像会读取 /config/proxus-mcp.json，并通过 stdin/stdout 使用 MCP，因此 MCP 客户端应以 docker 作为命令，并将 run -i --rm -v <folder>:/config ghcr.io/proxus-io/proxus-mcp:<version> 作为参数来启动它。主机上的设备可通过 host.docker.internal 访问；在 Linux 上添加 --network host，即可直接访问工厂网络。镜像适用于 linux/amd64 和 linux/arm64。

构建

需要 .NET 10 SDK。协议驱动程序来自 Proxus.Drivers NuGet 包（Apache-2.0）。

dotnet publish src/Proxus.Mcp.Server -c Release -r osx-arm64 -o artifacts/osx-arm64

构建结果是一个原生文件：artifacts/osx-arm64/proxus-mcp（约 10 MB）。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "proxus": {
      "command": "/absolute/path/to/proxus-mcp",
      "args": ["--config", "/absolute/path/to/proxus-mcp.json"]
    }
  }
}

复制 proxus-mcp.example.json，以此作为配置起点。

测试

• dotnet test tests/Proxus.Mcp.Tests：单元测试，无需设备。
• tests/smoke/run_all.sh：使用 Modbus 和 OPC UA 模拟器测试已发布的二进制文件（见 tests/smoke/README.md）。
• CI（.github/workflows/ci.yml）会运行这两项测试，并发布适用于 linux-x64、linux-arm64、win-x64 和 osx-arm64 的 Native AOT 二进制文件。

许可证

Apache-2.0，详见 LICENSE。