Mender MCP

🚀 Mender MCP Server

Model Context Protocol (MCP)サーバーは、Mender IoTプラットフォームとAIアシスタントをシームレスに統合します。AIアシスタントを通じて、自然言語で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. 設定に移動する:

   • 右上のプロフィール/アバターをクリックする
   • ドロップダウンメニューから**"Settings"**を選択する

3. パーソナルアクセストークンを作成する:

   • **"Personal Access Tokens"**タブに移動する
   • **"Generate new token"**をクリックする
   • トークン名: mender-mcp-integration（または説明的な名前）
   • 必要なパーミッション:
     • ✅ Device Management - デバイスのステータス、インベントリ、属性を読み取る
     • ✅ Deployment Management - デプロイメントのステータスと履歴を読み取る
     • ✅ Artifact Management - アーティファクトとリリースを表示する（オプション）
     • ✅ Device Logs - デプロイメントログにアクセスする（オプション、利用可能な場合）

4. トークンを保存する:

   • 生成されたトークンをすぐにコピーする（再度表示されない）
   • 以下の方法のいずれかを使用して安全に保存する

トークンの保存オプション

オプション1: 環境変数（推奨）

# ~/.bashrc、~/.zshrc、またはシェルプロファイルに追加する
export MENDER_ACCESS_TOKEN="your_personal_access_token_here"

# シェルを再読み込みするか、以下を実行する
source ~/.bashrc  # または ~/.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で、Settings → MCP Serversに移動する
   • または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デバイスと対話できます。

デバイス管理

"List all my Mender devices"
"Show me devices with status 'accepted'"
"Check the status of device abc123"
"What devices are offline?"
"Show me Raspberry Pi devices"

デプロイメント監視

"What deployments are currently running?"
"Show me the latest deployments"
"Check deployment status for ID def456"
"List failed deployments"
"What deployments finished today?"

デバイスインベントリとハードウェア

"What inventory information do you have for device abc123?"
"Show me hardware specs for all devices"
"List devices by device type"
"What Mender client versions are running?"

リリースとアーティファクト管理

"What releases are available?"
"Show me details for release mender-demo-artifact-3.8.2"
"List releases with 'demo' in the name"
"What artifacts are compatible with Raspberry Pi?"

トラブルシューティングとログ

"Get deployment logs for the latest failed deployment"
"Show me deployment logs for device abc123 in deployment def456"
"Why did my last deployment fail?"
"Show me error logs for failed deployments"

フリート分析と監視

"How many devices do I have in total?"
"What's the distribution of device types in my fleet?"
"Show me devices that haven't connected recently"
"Which devices are running outdated software versions?"
"What's the success rate of my recent deployments?"
"Show me devices grouped by their hardware platform"

セキュリティとコンプライアンス監視

"List devices with pending authorization"
"Show me devices that failed authentication"
"What devices have been rejected and why?"
"Check which devices need attention or manual intervention"
"Show me the security status of my device fleet"

運用インテリジェンス

"Compare deployment performance across different device types"
"What's the average deployment time for Raspberry Pi devices?"
"Show me deployment trends over the past week"
"Which releases have the highest failure rates?"
"Find devices with unusual inventory attributes"
"What's the geographic distribution of my devices?" (if location data available)

監査ログ

"Show me the audit logs for the last 24 hours"
"Get audit logs for user admin@company.com"
"Show me all device_accept actions in the logs"
"What deployment actions were performed yesterday?"
"Show me audit logs filtered by deployment object type"
"Get recent login attempts from the audit logs"

自動化ワークフロー

"Create a report of all failed deployments this month"
"Monitor deployment def456 and alert me if any devices fail"
"Check if all critical devices received the security update"
"Generate a fleet health summary for management review"
"Track the rollout progress of release 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）
• ✅ 定期的にトークンをローテーションする（本番環境では四半期ごとが推奨）
• ✅ 必要最小限のパーミッションを使用する（Device Management、Deployment Management）
• ❌ トークンをバージョン管理にコミットしたり、平文で共有したりしない

パフォーマンスに関する考慮事項

• APIレート制限: 合理的なリクエスト頻度でMenderのAPI制限を尊重する
• フリートサイズの拡張: 大規模なデバイスフリートには適切な制限値を使用する
• タイムアウト設定: 大規模なデプロイメントや低速なネットワークではタイムアウトを調整する
• メモリ使用量: 1000台以上のデバイスフリートではメモリ消費量を監視する

🐛 トラブルシューティング

一般的な問題

認証エラー:

Error: HTTP 401 - Authentication failed

• パーソナルアクセストークンが有効で期限切れでないことを確認する
• トークンにDevice ManagementとDeployment Managementのパーミッションがあることを確認する
• トークンが適切にフォーマットされていることを確認する（余分な空白や改行がないこと）

パーミッションエラー:

Error: HTTP 403 - Access denied

• 必要なパーミッション（Device Management、Deployment Management）を追加する
• Mender管理者に連絡してアカウントのアクセスレベルを確認する
• 組織アクセスが適切に構成されていることを確認する

接続問題:

Error: Request failed - Network error occurred

• MenderサーバーのURLが正しいことを確認する（https://hosted.mender.io）
• ネットワーク接続とファイアウォール設定を確認する
• MenderサーバーのDNS解決が機能することを確認する
• 同じURLにブラウザでアクセスしてテストする

設定問題:

Error: Command 'mcp-server-mender' not found

• 仮想環境がアクティブ化されていることを確認する: source venv/bin/activate
• インストールが正常に完了したことを確認する: pip install -e .
• PATHに仮想環境のbinディレクトリが含まれていることを確認する

デプロイメントログの問題

"No deployment logs found":

• これは成功したデプロイメントでは正常な現象です（通常、ログは失敗時のみ保持されます）
• 失敗したデプロイメントには詳細なログがあるはずです
• 一部の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でバグ報告や機能要求を行う
• コミュニティ: Mender Community Hubで一般的なIoTデバイス管理に関する議論を行う