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 設備管理討論