Mender MCP

🚀 Mender MCP 服务器

Mender MCP 服务器是一个用于模型上下文协议（MCP）的服务器，它能让 Mender IoT 平台与 AI 助手实现无缝集成。借助该服务器，AI 助手可以直接与 Mender IoT 平台交互，实现设备管理、部署跟踪和系统监控等功能。

🚀 快速开始

1. 安装

前提条件

• 系统中已安装 Python 3.8+
• 拥有一个有效的托管 Mender 账户
• 具备 Claude Code 或其他支持 MCP 的 AI 代理

从源代码安装

# 克隆仓库
git clone https://github.com/pasinskim/mender-mcp.git
cd mender-mcp

# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate  # 在 Windows 系统上使用：venv\\Scripts\\activate

# 安装软件包
pip install -e .

验证安装

# 测试服务器安装情况
mcp-server-mender --help

2. Mender 认证设置

获取个人访问令牌

1. 登录托管 Mender：

   • 访问 hosted.mender.io（或您的本地部署 URL）
   • 使用 Mender 账户凭据登录

2. 导航至设置：

   • 点击右上角的个人资料/头像
   • 从下拉菜单中选择 “设置”

3. 创建个人访问令牌：

   • 进入 “个人访问令牌” 选项卡
   • 点击 “生成新令牌”
   • 令牌名称：mender-mcp-integration（或其他描述性名称）
   • 所需权限：
     • ✅ 设备管理 - 读取设备状态、库存和属性
     • ✅ 部署管理 - 读取部署状态和历史记录
     • ✅ 工件管理 - 查看工件和版本信息（可选）
     • ✅ 设备日志 - 访问部署日志（可选，若可用）

4. 保存令牌：

   • 立即复制生成的令牌（令牌不会再次显示）
   • 使用以下方法之一安全存储令牌

令牌存储选项

选项 1：环境变量（推荐）

# 添加到 ~/.bashrc、~/.zshrc 或 shell 配置文件中
export MENDER_ACCESS_TOKEN="your_personal_access_token_here"

# 重新加载 shell 或运行以下命令
source ~/.bashrc  # 或 source ~/.zshrc

选项 2：安全令牌文件

# 创建安全的令牌目录
mkdir -p ~/.mender
chmod 700 ~/.mender

# 将令牌保存到文件中（请替换为实际令牌）
echo "your_personal_access_token_here" > ~/.mender/token
chmod 600 ~/.mender/token

3. Claude Code 集成

添加到 Claude Code 配置中

1. 打开 Claude Code 设置：

   • 在 Claude Code 中，进入设置 → MCP 服务器
   • 或直接编辑 MCP 配置文件

2. 添加 Mender MCP 服务器：

使用环境变量（推荐）

{
  "mcpServers": {
    "mender": {
      "command": "mcp-server-mender",
      "args": [
        "--server-url", "https://hosted.mender.io"
      ],
      "env": {
        "MENDER_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

使用令牌文件

{
  "mcpServers": {
    "mender": {
      "command": "mcp-server-mender", 
      "args": [
        "--server-url", "https://hosted.mender.io",
        "--token-file", "~/.mender/token"
      ]
    }
  }
}

对于本地部署的 Mender

{
  "mcpServers": {
    "mender": {
      "command": "mcp-server-mender",
      "args": [
        "--server-url", "https://your-mender-server.company.com",
        "--token-file", "~/.mender/token"
      ]
    }
  }
}

3. 重启 Claude Code 以加载新的 MCP 服务器配置。

✨ 主要特性

• 🔍 设备管理：列出、筛选和监控整个设备群中 IoT 设备的状态
• 🚀 部署跟踪：监控部署进度、成功率和失败分析
• 📊 实时监控：查看设备清单、硬件规格和系统属性
• 📝 部署日志：访问失败部署的详细日志以进行故障排除
• 🏷️ 版本管理：浏览版本、工件和兼容性信息
• 🔒 企业安全：基于令牌的认证，具备全面的输入验证
• 📋 只读操作：安全监控，无意外控制设备的风险
• 🌐 多平台支持：适用于托管 Mender 和本地部署

💻 使用示例

基础用法

配置完成后，您可以在 Claude Code 中使用自然语言与 Mender 设备进行交互：

设备管理

"列出我所有的 Mender 设备"
"显示状态为 '已接受' 的设备"
"检查设备 abc123 的状态"
"哪些设备处于离线状态？"
"显示树莓派设备"

部署监控

"当前正在运行哪些部署？"
"显示最新的部署"
"检查 ID 为 def456 的部署状态"
"列出失败的部署"
"今天完成了哪些部署？"

设备清单和硬件

"你有设备 abc123 的哪些清单信息？"
"显示所有设备的硬件规格"
"按设备类型列出设备"
"正在运行哪些 Mender 客户端版本？"

版本和工件管理

"有哪些可用的版本？"
"显示版本 mender-demo-artifact-3.8.2 的详细信息"
"列出名称中包含 'demo' 的版本"
"哪些工件与树莓派兼容？"

故障排除和日志

"获取最近一次失败部署的部署日志"
"显示设备 abc123 在部署 def456 中的部署日志"
"我上一次部署失败的原因是什么？"
"显示失败部署的错误日志"

设备群分析和监控

"我总共有多少台设备？"
"我的设备群中设备类型的分布情况如何？"
"显示最近未连接的设备"
"哪些设备正在运行过时的软件版本？"
"我最近的部署成功率是多少？"
"按硬件平台对设备进行分组显示"

安全和合规监控

"列出待授权的设备"
"显示认证失败的设备"
"哪些设备被拒绝了，原因是什么？"
"检查哪些设备需要关注或人工干预"
"显示我的设备群的安全状态"

运营智能

"比较不同设备类型的部署性能"
"树莓派设备的平均部署时间是多少？"
"显示过去一周的部署趋势"
"哪些版本的失败率最高？"
"查找具有异常清单属性的设备"
"我的设备的地理分布情况如何？"（如果有位置数据）

审计日志

"显示过去 24 小时的审计日志"
"获取用户 admin@company.com 的审计日志"
"显示日志中所有的 device_accept 操作"
"昨天执行了哪些部署操作？"
"显示按部署对象类型过滤的审计日志"
"从审计日志中获取最近的登录尝试信息"

自动化工作流

"创建本月所有失败部署的报告"
"监控部署 def456，如果有设备失败则提醒我"
"检查所有关键设备是否都收到了安全更新"
"生成设备群健康摘要供管理层审核"
"跟踪版本 v2.1.0 的推出进度"

高级用法

自定义日志和调试

启用调试日志

{
  "mcpServers": {
    "mender": {
      "command": "mcp-server-mender",
      "args": [
        "--server-url", "https://hosted.mender.io",
        "--token-file", "~/.mender/token"
      ],
      "env": {
        "MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

🔧 命令行界面

您也可以直接运行服务器进行测试：

# 使用环境变量
export MENDER_ACCESS_TOKEN="your_token"
mcp-server-mender --server-url https://hosted.mender.io

# 使用令牌文件
mcp-server-mender --server-url https://hosted.mender.io --token-file ~/.mender/token

# 直接使用令牌（不推荐）
mcp-server-mender --server-url https://hosted.mender.io --access-token your_token

# 本地部署
mcp-server-mender --server-url https://mender.company.com --token-file ~/.mender/token

📚 详细文档

MCP 工具（操作）

• get_device_status：获取特定设备的当前状态
• list_devices：列出设备并进行筛选（状态、设备类型、数量限制）
• get_deployment_status：检查部署进度和详细信息
• list_deployments：列出部署并按状态筛选
• get_deployment_device_log：获取特定设备的部署日志
• get_deployment_logs：获取部署中所有设备的部署日志
• get_release_status：获取特定版本的详细信息
• list_releases：列出版本并进行筛选（名称、标签、数量限制）
• get_device_inventory：获取设备的完整清单属性
• list_device_inventory：列出设备清单并进行筛选
• get_inventory_groups：获取所有设备清单组
• get_audit_logs：获取 Mender 审计日志并进行全面筛选（用户、操作、日期范围、对象类型）

MCP 资源（数据访问）

• mender://devices：完整的设备清单
• mender://deployments：所有部署
• mender://artifacts：可用的工件
• mender://releases：完整的版本目录
• mender://inventory：包含硬件规格和自定义属性的设备清单
• mender://inventory-groups：设备分组信息
• mender://audit-logs：用户操作和系统更改的系统审计日志
• mender://devices/{device_id}：特定设备的详细信息
• mender://deployments/{deployment_id}：特定部署的详细信息
• mender://releases/{release_name}：特定版本的详细信息

🔒 安全与最佳实践

令牌安全

• ✅ 使用环境变量 或安全令牌文件（而非直接配置）
• ✅ 设置适当的权限 对令牌文件（chmod 600 ~/.mender/token）
• ✅ 定期轮换令牌（生产环境建议每季度一次）
• ✅ 使用最小必要权限（设备管理、部署管理）
• ❌ 切勿将令牌提交 到版本控制或明文共享

性能考虑

• API 速率限制：以合理的请求频率遵守 Mender 的 API 限制
• 设备群规模扩展：对大型设备群使用适当的限制值
• 超时设置：为大型部署和慢速网络调整超时时间
• 内存使用：监控 1000 台以上设备群的内存消耗

🐛 故障排除

常见问题

认证错误

错误：HTTP 401 - 认证失败

• 验证您的个人访问令牌是否有效且未过期
• 检查令牌是否具有设备管理和部署管理权限
• 确保令牌格式正确（无额外空格或换行符）

权限错误

错误：HTTP 403 - 访问被拒绝

• 添加所需权限：设备管理、部署管理
• 联系您的 Mender 管理员以验证账户访问级别
• 检查组织访问是否配置正确

连接问题

错误：请求失败 - 发生网络错误

• 验证 Mender 服务器 URL 是否正确（https://hosted.mender.io）
• 检查网络连接和防火墙设置
• 确认 Mender 服务器的 DNS 解析是否正常
• 使用浏览器访问相同 URL 进行测试

配置问题

错误：未找到命令 'mcp-server-mender'

• 确保虚拟环境已激活：source venv/bin/activate
• 验证安装是否成功完成：pip install -e .
• 检查 PATH 是否包含虚拟环境的 bin 目录

部署日志问题

“未找到部署日志”

• 对于成功的部署，这是正常现象（日志通常仅保留失败情况）
• 失败的部署应该有详细的日志可用
• 某些 Mender 配置默认不启用部署日志记录

日志为空或截断

• 大型部署可能由于大小限制导致日志截断
• 检查设备端日志以获取更详细的信息
• 考虑部署大小和超时设置

获取帮助

1. 检查服务器连接性：使用 mcp-server-mender --help 进行测试
2. 验证 Mender 访问权限：使用相同的凭据登录 Mender 网页界面
3. 手动测试令牌：使用 Mender API 文档直接测试令牌
4. 启用调试日志：设置 MCP_LOG_LEVEL=DEBUG 以获取详细输出
5. 查看 Claude Code 日志：检查 Claude Code 的 MCP 连接状态

🧪 开发与测试

运行测试

# 激活虚拟环境
source venv/bin/activate

# 安装测试依赖项
pip install pytest

# 运行所有测试
pytest tests/

# 仅运行安全测试
pytest tests/test_security.py -v

# 运行测试并生成覆盖率报告
pip install pytest-cov
pytest tests/ --cov=src/mcp_server_mender

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献！请阅读我们的贡献指南，并提交拉取请求以进行任何改进。

📞 支持

• 文档：本 README 和内联帮助（--help）
• 问题反馈：在 GitHub Issues 中报告 bug 和提出功能请求
• 社区：Mender 社区中心，用于一般 IoT 设备管理讨论