MIRASTACK Redfish MCP Server

MIRASTACK Redfish MCP 服务

面向符合 DMTF Redfish 标准的 BMC 的受管 MCP 服务——适用于 iDRAC、iLO、XCC、 OpenBMC 及兼容实现。默认只读：除非显式提高写入模式，否则不会注册变更工具；所有变更在确认前都只是试运行。

由 MIRASTACK LABS 构建。Apache-2.0。

主要特点

• 通过官方 Python MCP SDK 提供 MCP stdio 和 streamable-http 传输方式。
• 从 DMTF Redfish-Publications 提炼的架构元数据，固定使用 2026.1 版本。
• 符合协议规范的 Redfish 行为：会话身份验证、ETag/If-Match、202 任务轮询，以及基于注册表的错误呈现。
• 安全写入控制：分级注册，并优先采用试运行确认机制。

项目缘由

BMC 是一个位于操作系统启动前的带外控制平面，其权限高于常规主机级 root 访问权限。在缺乏严格防护措施的情况下向自主 Agent 提供 BMC 访问权限，会立即带来涉及电源、启动、固件和账户边界的重大影响风险。本服务会将危险操作置于有意提升写入模式的流程之后，并默认让所有变更处于试运行状态，以便在应用前审查操作意图。由此形成的是受管操作界面，而非随时待命的远程控制器。模型仍可快速执行诊断，但权限转换会变得明确且可审计。

安装

pip install mirastack-redfish-mcp

60 秒快速体验（无需硬件）

运行本地 DMTF mockup，以只读模式启动 MCP 服务，然后调用一个读取工具：

docker compose -f examples/mockup/docker-compose.yml up -d
export MIRASTACK_REDFISH_HOST="http://127.0.0.1:18000"
export MIRASTACK_REDFISH_USERNAME="<bmc-username>"
export MIRASTACK_REDFISH_PASSWORD="<bmc-password>"
export MIRASTACK_REDFISH_WRITE_MODE="off"
mirastack-redfish-mcp --transport stdio

工具调用示例：

{"tool":"service_info","arguments":{}}

预期输出格式：

{
  "endpoint": "default",
  "service_root": {
    "@odata.id": "/redfish/v1"
  },
  "capabilities": {
    "redfish_version": "..."
  }
}

发现模式

服务也可以在没有任何端点凭据的情况下启动，并仍提供只读工具发现功能（用于 MCP 扫描器验证和元数据索引）。在此模式下，基于架构/语料库的工具仍可使用，而连接 BMC 的工具会返回配置错误，并指出所需的环境变量： MIRASTACK_REDFISH_HOST、MIRASTACK_REDFISH_USERNAME 和 MIRASTACK_REDFISH_PASSWORD（或 MIRASTACK_REDFISH_PASSWORD_FILE），或者用于多端点配置的 MIRASTACK_REDFISH_ENDPOINTS。

发现模式也适用于端点文件缺失的情况。如果 MIRASTACK_REDFISH_ENDPOINTS 指向的路径不存在——容器平台和 MCP 目录扫描器通常会注入占位路径——服务会在 stderr 上记录一条包含该路径的警告，并以零个端点启动。若文件确实存在，但无法读取或解析，则仍会导致启动失败；单个端点配置不完整（例如设置了 MIRASTACK_REDFISH_HOST，但没有设置 MIRASTACK_REDFISH_PASSWORD）时仍会引发错误，因此拼写错误绝不会悄然使已配置的部署降级。

快速入门（硬件，stdio）

export MIRASTACK_REDFISH_HOST="https://192.0.2.10"
export MIRASTACK_REDFISH_USERNAME="<bmc-username>"
export MIRASTACK_REDFISH_PASSWORD="<bmc-password>"
export MIRASTACK_REDFISH_WRITE_MODE="off"
mirastack-redfish-mcp --transport stdio

快速入门（streamable-http）

mirastack-redfish-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --path /mcp \
  --stateless-http \
  --json-response

**警告：**绑定到 0.0.0.0 会将 BMC 控制权限暴露给所有能够访问此端口的主机。除非监听器位于受信任管理网络上的身份验证代理之后，否则请绑定到回环地址。

配置

规范环境变量

使用 MIRASTACK_REDFISH_* 变量：

• MIRASTACK_REDFISH_HOST
• MIRASTACK_REDFISH_USERNAME
• MIRASTACK_REDFISH_PASSWORD 或 MIRASTACK_REDFISH_PASSWORD_FILE
• 可选：MIRASTACK_REDFISH_VERIFY_SSL（默认值：true）、MIRASTACK_REDFISH_CA_BUNDLE、MIRASTACK_REDFISH_TIMEOUT_SEC、MIRASTACK_REDFISH_AUTH_MODE

多端点配置

将 MIRASTACK_REDFISH_ENDPOINTS 设置为内联 JSON 或 YAML/JSON 文件：

{
  "idrac-prod": {
    "base_url": "https://192.0.2.10",
    "username": "<bmc-username>",
    "password_file": "/run/secrets/idrac_password",
    "verify_ssl": true,
    "read_only": true
  },
  "ilo-lab": {
    "base_url": "https://192.0.2.11",
    "username": "<bmc-username>",
    "password": "<bmc-password>",
    "verify_ssl": true
  }
}

仅限实验室的覆盖设置（不建议用于生产环境）：

{
  "ilo-lab": {
    "verify_ssl": false
  }
}

设置 MIRASTACK_REDFISH_DEFAULT_ENDPOINT 以选择默认端点。

兼容性

仍会将旧版裸 REDFISH_* 环境变量作为回退读取，每个变量只会发出一次弃用警告。

工具注册配置

• MIRASTACK_REDFISH_TOOL_PROFILE=full（默认）：允许注册写入模式支持的所有工具集。
• MIRASTACK_REDFISH_TOOL_PROFILE=standard：排除原始写入的应急通道。
• MIRASTACK_REDFISH_TOOL_PROFILE=core：为小型模型精选的 15 个工具。
• MIRASTACK_REDFISH_TOOLSETS（逗号分隔）会使用显式工具集覆盖配置。

在 MIRASTACK_REDFISH_WRITE_MODE=full 时测得的工具架构负载大小：core 为 20,795 字节（15 个工具），standard 为 43,669 字节（33 个工具），full 为 54,745 字节（40 个工具）。使用 python3 scripts/check_tool_metadata.py --sizes 重新测量。

写入安全模型

• MIRASTACK_REDFISH_WRITE_MODE=off（默认）：不注册变更类工具。
• MIRASTACK_REDFISH_WRITE_MODE=power：注册电源／重置／启动控制工具。
• MIRASTACK_REDFISH_WRITE_MODE=config：注册配置层级工具。
• MIRASTACK_REDFISH_WRITE_MODE=full：注册完整层级工具。

每个变更类工具都接受 confirm：

• confirm=false：返回试运行响应（dry_run=true、applied=false），并包含 next_step。
• confirm=true：执行操作。

端点级别的 read_only=true 会覆盖全局写入模式，并阻止该端点上的所有写入操作。

层级约定

• 电源层级： set_power_state、set_boot_override、reset_manager、cancel_task
• 配置层级： set_bios_attributes、eject_virtual_media、redfish_patch、redfish_post、redfish_delete、redfish_invoke_action
• 完整层级： insert_virtual_media、clear_logs、manage_account、simple_update、reset_to_defaults

开发

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
make build-index
make verify

架构索引根据 DMTF Redfish-Publications 生成，并固定到一个版本以确保可复现。刷新流程请参阅 CONTRIBUTING.md。

注册表发布说明

• server.json 包含供 MCP Registry 使用的 PyPI 和 OCI 软件包定义。
• 本 README 包含必需的标记：mcp-name: ai.mirastacklabs/mirastack-redfish-mcp。
• Docker 镜像包含 io.modelcontextprotocol.server.name OCI 标签。
• 使用 Homebrew 安装官方发布 CLI：brew install mcp-publisher。
• 发布到注册表时，请勿使用 npx mcp-publisher 或 pip install mcp-publisher。

容器和目录部署

发布的镜像会将控制台脚本添加到 PATH，因此 docker run ... mirastack-redfish-mcp --transport stdio 无需修改即可运行。

某些 MCP 目录会忽略仓库的 Dockerfile，并根据源代码生成自己的镜像。如果生成的构建使用 uv sync 安装，项目会被放在 /app/.venv 虚拟环境中，控制台脚本不会位于 PATH 中，因此通过裸名称启动的启动器会因 ENOENT 而失败。请改为将启动器指向绝对路径：

{
  "buildSteps": ["uv sync"],
  "cmdArguments": ["/app/.venv/bin/mirastack-redfish-mcp", "--transport", "stdio"]
}

如果平台从未创建占位路径 MIRASTACK_REDFISH_ENDPOINTS，则不会有问题——服务会以发现模式启动，并提供只读工具集。

贡献

GitHub 是公开的只读镜像。欢迎在 GitHub 上提交问题，但在 GitHub 上发起的拉取请求无法合并。请参阅 CONTRIBUTING.md，了解接受的贡献方式。

安全

请参阅 SECURITY.md。

许可证

Apache-2.0。