Ignition MCP

ignition-mcp

适用于 Inductive Automation Ignition 的 MCP（模型上下文协议）服务。它为 AI 助手、Claude Desktop、Claude Code 或任何 MCP 客户端提供对 Ignition 网关的结构化访问：浏览和写入标签、查询历史记录和警报、管理项目，以及部署完整的 Perspective 视图。

已针对 Ignition 8.3 测试。提供 43 个工具，涵盖标签、历史记录、警报、项目、网关管理和 Perspective。服务默认只读；所有写入操作都必须显式启用。

You:    "Deploy a Perspective dashboard to a new project called LineOverview with a
         gauge bound to [default]Line1/Speed."
Claude: (bootstraps the project, writes the view, wires the tag binding, triggers a scan)
        -> https://gateway:8088/data/perspective/client/LineOverview

为什么采用双通道

Ignition 8.3 内置了 REST API，但无法访问实时标签值、标签历史记录、警报查询或 Perspective 视图资源。ignition-mcp 通过两个传输通道弥补了这一缺口：

• REST 通道。 网关原生的 /data/api/v1 API，使用 API 密钥进行身份验证，用于项目、网关配置、模块、日志、备份和 Perspective 会话诊断。
• Bridge 通道。 一个小型 WebDev 项目（mcp-bridge），只需在网关上安装一次。它通过 HMAC 签名的 HTTP 请求公开网关脚本接口（system.tag.*、system.alarm.*、system.db.* 和项目文件 I/O）。

如果未安装 Bridge，依赖它的工具会提供清晰的提示并降级。随时运行 ignition_diagnose，查看已配置的内容和缺少的内容。

快速开始

1. 在网关上创建 API 密钥

网关 Web UI -> Config -> Security -> API Keys -> Create。为密钥命名，例如 claude。复制完整令牌；其格式类似 claude:AbCd...。

自动创建的密钥安全级别（Authenticated/<key-name>）需要在 Config -> Security -> General -> Gateway Read/Write Permissions 下授予网关读写权限。跳过此步骤会导致调用返回 HTTP 403；ignition_diagnose 会告知你问题并提供确切的修复方法。

2. 安装 ignition-mcp

pipx install ignition-mcp
# or: uvx ignition-mcp
# or: pip install ignition-mcp

3. 配置 MCP 客户端

Claude Desktop（claude_desktop_config.json）或 Claude Code（.mcp.json）：

{
  "mcpServers": {
    "ignition": {
      "command": "ignition-mcp",
      "env": {
        "IGNITION_URL": "http://localhost:8088",
        "IGNITION_API_TOKEN": "claude:YOUR_SECRET_HERE"
      }
    }
  }
}

重启客户端，并让它运行 ignition_diagnose。你应该会看到一份全绿的检查清单，但会有一条关于 Bridge 的警告；下一步将处理此问题。

4. 安装 Bridge（推荐；实时数据和 Perspective 部署所必需）

生成一个随机密钥，启用写入，并让服务替你安装 Bridge：

"env": {
  "IGNITION_URL": "http://localhost:8088",
  "IGNITION_API_TOKEN": "claude:YOUR_SECRET_HERE",
  "IGNITION_BRIDGE_SECRET": "a-long-random-string",
  "IGNITION_ALLOW_WRITES": "true"
}

让你的助手安装 Bridge（这会运行 bridge_install 工具），然后再次运行 ignition_diagnose，确认 Bridge 检查项显示为绿色。手动安装步骤和故障排查请参阅 docs/bridge.md。

配置

变量	必填	默认值	含义
IGNITION_URL	是	无	网关基础 URL，例如 http://localhost:8088
IGNITION_API_TOKEN	是	无	API 密钥，格式为 name:secret
IGNITION_BRIDGE_SECRET	否	未设置	Bridge 的 HMAC 密钥；未设置时会禁用 Bridge 工具
IGNITION_ALLOW_WRITES	否	false	所有修改类工具的总开关
IGNITION_TLS_VERIFY	否	true	对使用自签名证书的开发网关设为 false
IGNITION_TIMEOUT_S	否	30	每次请求的超时时间，单位为秒
IGNITION_TAG_WRITE_ALLOWLIST	否	未设置	逗号分隔的 glob 模式；拒绝写入不匹配的标签

安全模型

• 默认只读。除非设置 IGNITION_ALLOW_WRITES=true，且调用通过 confirm=true 验证，否则修改类工具不会运行。你批准操作后，助手会设置 confirm。
• 破坏性操作会回显名称。删除项目或视图时，必须重新发送其确切名称。
• 标签写入允许列表可将可写标签限制为指定的路径 glob 模式。
• REST 修改操作会将 API 密钥的身份记录到 Ignition 自身的审计日志中；Bridge 修改操作则记录到 mcp-bridge 日志记录器。密钥绝不会被记录或回显。
• Bridge 的文件端点仅限于 data/projects/；无法访问该目录树以外的内容。

工具目录

区域	工具
诊断	ignition_diagnose、gateway_info、gateway_trial_status、gateway_trial_reset
标签	tag_browse、tag_read、tag_write、tag_create、tag_config_export、tag_config_import
历史记录	history_query、history_providers
警报	alarm_status、alarm_journal、alarm_acknowledge
项目	project_list、project_get、project_create、project_delete、project_export、project_import、project_scan
Perspective	perspective_bootstrap_project、perspective_list_views、perspective_get_view、perspective_upsert_view、perspective_delete_view、perspective_validate_view、perspective_page_config_get/set、perspective_session_props_get、perspective_style_upsert、perspective_list_sessions
Gateway 管理	gateway_modules、gateway_logs_query、gateway_logger_set_level、gateway_backup、gateway_performance、config_resource_list
数据库	db_run_named_query、db_query
桥接	bridge_install、bridge_status

服务还提供了 MCP 资源，助手可以读取这些资源来编写有效的 Perspective 视图： ignition://docs/view-schema 和 ignition://templates/view/{flex-basic,coordinate-basic,tag-bound-dashboard}。

构建 Perspective 视图

完整说明请参阅 docs/perspective-authoring.md。简而言之：助手读取视图架构资源，从模板开始，使用 perspective_validate_view 进行离线验证，然后通过 perspective_upsert_view 部署。该工具会再次验证、写入视图并触发项目扫描。完整的往返示例请见 examples/deploy-dashboard.md。

开发

git clone https://github.com/jsgorana/ignition-mcp
cd ignition-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check src tests          # lint
ruff format --check src tests # format check
mypy src                      # type check
pytest tests/unit             # unit tests, no gateway needed
python bridge/build_zip.py    # rebuild the bridge project archive

# Live integration suite (needs a real 8.3 gateway with the bridge installed):
IGNITION_URL=... IGNITION_API_TOKEN=... IGNITION_BRIDGE_SECRET=... \
IGNITION_ALLOW_WRITES=true python tests/live/live_check.py

致谢

本项目基于 Model Context Protocol 及其 Python SDK 构建，并使用 httpx 处理 HTTP。ignition-sdk-examples 仓库 为了解 Ignition 的模块和脚本 API 如何协同工作提供了有益参考。

许可证

MIT。请参阅 LICENSE。

免责声明

本项目由社区独立构建，与 Inductive Automation 无关联，也未获其认可或赞助。“Ignition”和“Perspective”是 Inductive Automation, LLC 的商标，在此仅用于描述兼容性。请先在非生产环境的 Gateway 上测试任何启用了写入功能的工具，再将其用于重要环境。