Keeper MCP Golang Docker

🚀 KSM MCPサーバー - Keeperシークレットへの安全なAIアクセス

KSM MCPは、Model Context Protocol (MCP)サーバーで、AI言語モデル（Claudeなど）とKeeper Secrets Manager (KSM)の間の安全な仲介役として機能します。これにより、AIエージェントがKSMのシークレットを管理することができます。具体的には、レコードやフォルダの一覧表示、作成、取得、削除などの操作が可能です。同時に、KSMアプリケーションの資格情報を保護します。機密性の高い操作にはユーザーの確認が必要で、データの管理をユーザーがコントロールし続けることができます。

🚀 クイックスタート

オプション1: Dockerを使用する（推奨）

1. KSMのBase64構成を取得する

   • Keeper Secrets Vaultにログインします。
   • Secrets Manager、Applicationに移動し、「Devices」タブをクリックします。
   • 「Add Device」をクリックし、提供されるBase64エンコードされた構成文字列をコピーします（通常はewog...で始まります）。

   ⚠️ 重要な注意

   Base64構成にはKSMアプリケーションの資格情報が含まれています。安全に保管し、バージョン管理システムにコミットしないでください。

2. Claude Desktopを設定する

   • Claude Desktopの設定ファイルを開きます。
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json
     • Linux: ~/.config/Claude/claude_desktop_config.json
   • ksmサーバーエントリを以下のように追加または更新し、YOUR_BASE64_CONFIG_STRING_HEREを実際のBase64構成に置き換えます。

   {
     "mcpServers": {
       "ksm": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING_HERE",
           "keepersecurityinc/ksm-mcp-poc:latest"
         ]
       }
       // ここに「memory」などの他のサーバーがある場合は、そのままにしておきます。
     }
   }
   

3. Claude Desktopを再起動する

   • これでClaudeからKSMサーバーが利用可能になります。初回接続時には、Base64構成を使用して起動します。

オプション2: 事前コンパイル済みのバイナリを使用する

1. バイナリをダウンロードする

   • KSM MCP Releases Pageにアクセスし、オペレーティングシステムに適したバイナリをダウンロードします（例: Intel Macの場合はksm-mcp-darwin-amd64、Windowsの場合はksm-mcp-windows-amd64.exe）。
   • バイナリを実行可能にし（例: chmod +x ./ksm-mcp-darwin-amd64）、システムのPATHに含まれるディレクトリに配置するか、その完全パスをメモします。

2. KSMのBase64構成を取得する（上記のDockerガイドの手順1を参照）

   ⚠️ 重要な注意

   Base64構成にはKSMアプリケーションの資格情報が含まれています。安全に保管し、バージョン管理システムにコミットしないでください。

3. KSM MCPプロファイルを初期化する

   • ターミナルを開き、initコマンドを実行し、YOUR_BASE64_CONFIG_STRINGを置き換え、プロファイル名（例: default）を選択します。

   /path/to/ksm-mcp init --profile default --config "YOUR_BASE64_CONFIG_STRING"
   

   • ローカルプロファイルストアの保護パスワードを設定するように求められます。このパスワードを覚えておいてください。手動でサーバーを再起動する場合や、パスワードが必要なように設定されている場合に必要になります。Claudeとの自動化された使用では、多くの場合、サーバーはバッチモードで実行され、このパスワードは対話的に要求されません。

4. Claude Desktopを設定する

   • claude_desktop_config.jsonファイルを開きます（Dockerガイドのパスを参照）。
   • ksmサーバーエントリを追加または更新し、/path/to/ksm-mcpをダウンロードしたバイナリの実際のパスに置き換えます。

   {
     "mcpServers": {
       "ksm": {
         "command": "/path/to/ksm-mcp",
         "args": ["serve", "--profile", "default"] // 初期化したプロファイル名を使用します。
       }
       // ... 他のサーバー ...
     }
   }
   

5. Claude Desktopを再起動する

✨ 主な機能

KSM MCPサーバーは、Keeper Secrets Managerとやり取りするための以下のツールを提供します。

シークレット操作

• list_secrets: アクセス可能なすべてのシークレットの一覧を表示します（メタデータのみ）。
• get_secret: 特定のシークレットを取得します（デフォルトでは機密フィールドはマスクされています。マスクを解除するには確認が必要です）。
• search_secrets: タイトル、ノート、または他のフィールドの内容でシークレットを検索します。
• create_secret: 新しいシークレットを作成します（確認が必要です）。
• update_secret: 既存のシークレットを更新します（確認が必要です）。
• delete_secret: シークレットを削除します（確認が必要です）。

フォルダ操作

• list_folders: アクセス可能なすべてのフォルダの一覧を表示します。
• create_folder: 新しいフォルダを作成します（確認が必要です。親の共有フォルダを指定する必要があります）。
• delete_folder: フォルダを削除します（確認が必要です。空でないフォルダを強制削除するオプションがあります）。

ファイル管理（シークレット内）

• upload_file: シークレットにファイル添付をアップロードします（確認が必要です）。
• download_file: シークレットからファイル添付をダウンロードします。

ユーティリティ

• generate_password: 安全なパスワードを生成します。オプションで、AIにパスワードを公開せずに新しいシークレットに直接保存することができます。
• get_totp_code: TOTPが設定されたシークレットの現在のTOTPコードを取得します。
• get_server_version: KSM MCPサーバーの現在のバージョンを取得します。
• health_check: MCPサーバーの動作状態とKSMへの接続を確認します。

📚 ドキュメント

サンプルユースケース

以下は、AIエージェント（Claudeなど）にKSM MCPサーバーを使用するように指示する例です。

• 新しいフォルダに新しいシークレットを作成する "メインの'KSM-MCP-TEST-RECORDS'共有フォルダの下に'Project Phoenix Shared'という名前の新しいフォルダを作成してください。次に、'Project Phoenix Shared'の中に、ユーザー名が'phoenix_user'、パスワードが'ComplexP@$$wOrd123!'、URLが'db.phoenix.dev.internal'の新しいログインシークレットを作成してください。"

• シークレットを一覧表示し、1つを取得する "API Keys'フォルダ内のすべてのシークレットを一覧表示してください。次に、'Third-Party Analytics API Key'というタイトルのシークレットの詳細を取得し、APIキー自体はマスクしたままにしてください。"

• シークレットを削除し、その後そのフォルダを削除する（空の場合） "Old Staging Server Credentials'という名前のシークレットを削除してください。それが完了したら、そのシークレットが属していた'Staging Environment'フォルダが空になった場合は、そのフォルダも削除してください。"

• 既存のレコードに構成ファイルをアップロードする "私は'~/Downloads/kubeconfig-prod.yaml'にある本番クラスター用の新しいKubernetes構成ファイルを持っています。このファイルを'Production K8s Cluster Access'というタイトルのKSMレコードにアップロードし、添付ファイル名を'kubeconfig-prod-cluster.yaml'としてください。"

• 安全なパスワードを生成し、新しいレコードに保存する "大文字、小文字、数字、および特殊文字を含む非常に強力な32文字のパスワードを生成してください。これを'Service Accounts'フォルダ内の'Internal Audit Service Account'というタイトルの新しいログインレコードに直接保存してください。パスワードを表示しないでください。"

• 環境間の構成の一貫性を確認する "私はサービス構成レコードを環境（開発、QA）ごとにフォルダで整理し、各AWSリージョンにサブフォルダを作成しています。これらのレコードを分析し、異なる環境間の同様のサービスの間で不一致があるかどうかを特定してください。特に、環境間で通常同じであるべき構成値、たとえばログレベル、タイムアウト設定、または機能フラグに注意を払ってください。"

サーバー構成リファレンス

KSM MCPサーバーは、さまざまな構成オプションを使用して複数の方法でインスタンス化できます。このセクションでは、利用可能なすべての方法、フラグ、および環境変数について説明します。

構成方法

方法1: 環境変数を使用したDocker（推奨）

{
  "mcpServers": {
    "ksm": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING",
        "keepersecurityinc/ksm-mcp-poc:latest"
      ]
    }
  }
}

方法2: プロファイルを使用した事前コンパイル済みのバイナリ

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve", "--profile", "default"]
    }
  }
}

方法3: Base64構成を使用した事前コンパイル済みのバイナリ（CLIフラグ）

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": [
        "serve",
        "--config-base64", "YOUR_BASE64_CONFIG_STRING"
      ]
    }
  }
}

方法4: 環境変数を使用した事前コンパイル済みのバイナリ

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve"],
      "env": {
        "KSM_CONFIG_BASE64": "YOUR_BASE64_CONFIG_STRING"
      }
    }
  }
}

方法5: サイレントモード（ローカルログなし）

ローカルファイルの作成を防止したい環境では、以下のように設定します。

{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": [
        "serve",
        "--no-logs",
        "--config-base64", "YOUR_BASE64_CONFIG_STRING"
      ]
    }
  }
}

--no-logsフラグは、監査ログを完全に無効にして、ローカルファイルが作成されないようにします。これは以下の場合に役立ちます。

• ローカルファイルの作成を避けなければならないコンプライアンス環境
• 永続化が必要ないコンテナ化されたデプロイメント
• 一時的またはテストシナリオ
• 読み取り専用のファイルシステムを持つシステム

コマンドラインフラグ

フラグの詳細

--batch（非対話モード）

• 目的: サーバーがパスワードやユーザー入力を求めないようにします。
• 使用する場合:
  • 自動化された環境（CI/CD、Dockerコンテナ）
  • 人間の操作が不可能なサービスとして実行する場合
  • Claude Desktopとの統合（推奨）
• 動作:
  • 暗号化されたプロファイルを読み込む際のパスワードプロンプトをスキップします。
  • すべての構成に環境変数またはCLIフラグを使用します。
  • 必要な入力が不足している場合は、ハングする代わりに適切に失敗します。

--no-logs（サイレントモード）

• 目的: ローカルファイルの作成を防ぐために、監査ログを完全に無効にします。
• 使用する場合:
  • ローカルアーティファクトを避けなければならないコンプライアンス環境
  • コンテナ化または一時的なデプロイメント
  • 読み取り専用のファイルシステムを持つ環境
  • クリーンアップが重要なテストシナリオ
• 動作:
  • ~/.keeper/ksm-mcp/logs/ディレクトリの作成を防止します。
  • すべての監査ログ（アクセスログ、エラーログ、システムログ）を無効にします。
  • ログのオーバーヘッドなしで完全なMCP機能を維持します。
  • すべてのログ呼び出しに対してnilチェックラッパーで安全に動作します。
• セキュリティ: 高 - 機密データがローカルファイルに書き込まれません。

--auto-approve（危険）

• 目的: 破壊的操作のユーザー確認プロンプトをバイパスします。
• ⚠️ セキュリティ警告: これは危険であり、制御された環境でのみ使用する必要があります。
• 通常確認が必要な操作:
  • create_secret - 新しいシークレットを作成する
  • update_secret - 既存のシークレットを変更する
  • delete_secret - シークレットを削除する
  • create_folder - 新しいフォルダを作成する
  • delete_folder - フォルダを削除する
  • upload_file - シークレットにファイルをアップロードする
  • 機密データ（パスワード、APIキーなど）のマスクを解除する
• 使用する場合:
  • 自動化されたテスト環境
  • 制御されたシナリオでの信頼できるAIエージェント
  • 手動確認が実用的でない大量の操作
• 推奨される代替手段: 選択的な承認にはksm_execute_confirmed_actionツールを使用します。

環境変数

構成の優先順位

サーバーは、構成に以下の優先順位を使用します。

1. CLIフラグ --config-base64（最も高い優先順位）
2. 環境変数 KSM_CONFIG_BASE64
3. CLIフラグ --profile とローカルプロファイルストレージ
4. 環境変数 KSM_MCP_PROFILE とローカルプロファイルストレージ

プロファイル管理コマンド

プロファイルを使用する理由

プロファイルは、機密資格情報を公開せずにKSM構成をローカルに安全に保存および管理する方法を提供します。

• セキュリティ: Base64構成には機密性の高いKSMアプリケーションの資格情報が含まれています。プロファイルはこれらをパスワードで保護してローカルに暗号化して保存します。
• 利便性: 一度初期化すると、毎回完全なBase64構成を渡す代わりに、プロファイル名を参照するだけで済みます。
• 複数の環境: 別々のプロファイルで異なるKSMアプリケーション（開発、ステージング、本番）を管理できます。
• 資格情報の保護: 機密データをコマンドライン、環境変数、および構成ファイルから除外します。
• 永続的なストレージ: システムの再起動後も保持され、資格情報を再入力する必要がありません。

プロファイルと直接構成を使用する場合:

• プロファイルを使用する場合: ローカル開発、永続的なセットアップ、複数の環境
• 直接構成を使用する場合: CI/CD、Dockerコンテナ、一時的な使用、ローカルストレージが望まれない環境

新しいプロファイルを初期化する

ksm-mcp init --profile PROFILE_NAME --config "BASE64_CONFIG_STRING"

このコマンドは以下のことを行います。

1. Base64のKSM構成を取得します。
2. 提供したパスワードで暗号化します。
3. ~/.keeper/ksm-mcp/profiles/にローカルに保存します。
4. 将来は--profile PROFILE_NAMEだけで使用できます。

利用可能なプロファイルを一覧表示する

ksm-mcp profiles list

プロファイルを削除する

ksm-mcp profiles delete --profile PROFILE_NAME

セキュリティに関する考慮事項

トラブルシューティング

一般的な問題

1. "No active session"エラー: 以下のいずれかが設定されていることを確認してください。

   • 初期化されたプロファイルを指す有効な--profileフラグ
   • 有効な--config-base64フラグまたはKSM_CONFIG_BASE64環境変数

2. "Failed to create log directory"警告: --no-logsフラグを使用してローカルログを無効にします。

3. Permission deniedエラー: バイナリに実行権限があり、構成ディレクトリが書き込み可能であることを確認してください。

デバッグモード

トラブルシューティングのためにデバッグログを有効にします。

ksm-mcp serve --log-level debug --profile your-profile

例

開発セットアップ

# プロファイルを初期化する
ksm-mcp init --profile dev --config "ewogICJob3N0bmFtZSI6..."

# サーバーを起動する
ksm-mcp serve --profile dev --log-level debug

本番セットアップ（Docker）

docker run -i --rm \
  -e KSM_CONFIG_BASE64="ewogICJob3N0bmFtZSI6..." \
  keepersecurityinc/ksm-mcp-poc:latest

CI/CDセットアップ（ローカルファイルなし）

export KSM_CONFIG_BASE64="ewogICJob3N0bmFtZSI6..."
ksm-mcp serve --no-logs --batch --timeout 60s