KSM MCP Server - Secure AI Access to Keeper Secrets

KSM MCP サーバー - Keeper Secrets への安全な AI アクセス

KSM MCP は、AI 言語モデル（Claude など）と Keeper Secrets Manager（KSM）の間で安全な仲介役として機能する Model Context Protocol（MCP）サーバーです。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
   • YOUR_BASE64_CONFIG_STRING_HERE を実際の Base64 設定に置き換えて、次のように ksm サーバーのエントリを追加または更新します。

   {
     "mcpServers": {
       "ksm": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING_HERE",
           "keeper/keeper-mcp-server:latest"
         ]
       }
       // You might have other servers like "memory" here, leave them as is.
     }
   }
   

3. Claude Desktop を再起動します：

   • KSM サーバーが Claude から利用できるようになります。初回の接続時に、Base64 設定を使用して起動します。

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

1. バイナリをダウンロードします：

   • KSM MCP リリースページにアクセスし、ご使用のオペレーティングシステムに適したバイナリをダウンロードします（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 ガイドを参照）。
   • ダウンロードしたバイナリの実際のパスに /path/to/ksm-mcp を置き換えて、ksm サーバーのエントリを追加または更新します。

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

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』の、『Phoenix Dev DB』というタイトルの新しいログインシークレットを作成してください。」

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

• シークレットを削除し、空の場合はそのフォルダーも削除する： 「『Old Staging Server Credentials』という名前のシークレットを削除してください。完了したら、そのシークレットが入っていた『Staging Environment』フォルダーが空になっている場合は、そのフォルダーも削除してください。」

• 既存のレコードに設定ファイルをアップロードする： 「本番クラスター用の新しい Kubernetes 設定ファイル『~/Downloads/kubeconfig-prod.yaml』があります。このファイルを『Production K8s Cluster Access』というタイトルの KSM レコードにアップロードし、添付ファイル名を『kubeconfig-prod-cluster.yaml』にしてください。」

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

• 環境間の設定の一貫性を確認する： 「環境（dev、qa）ごとにフォルダー分けされ、さらに各 AWS リージョンのサブフォルダーがあるサービス設定レコードがあります。これらのレコードを分析し、異なる環境間で類似サービスに一貫性がない箇所を特定してください。特に、ログレベル、タイムアウト設定、機能フラグなど、通常は環境間で同じであるべき設定値に注目してください。」

---

サーバー設定リファレンス

KSM MCP サーバーは、さまざまな設定オプションを使って複数の方法で起動できます。このセクションでは、利用可能なすべての方法、フラグ、環境変数について説明します。

設定方法

方法 1：環境変数を使った Docker（推奨）

{
  "mcpServers": {
    "ksm": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING",
        "keeper-mcp-server: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 フラグを指定すると監査ログが完全に無効になり、ローカルでファイルが作成されなくなります。これは次のような場合に便利です。

• ローカルでのファイル作成を避ける必要があるコンプライアンス環境
• 永続化が不要なコンテナ化されたデプロイ
• 一時的な利用やテストのシナリオ
• 読み取り専用ファイルシステムを使用するシステム

コマンドラインフラグ

フラグ	型	デフォルト	説明
--profile	string	""	ローカルストレージから使用するプロファイル名
--config-base64	string	""	Base64 エンコードされた KSM 設定文字列
--batch	boolean	false	バッチモードで実行します（パスワードの入力を求めません。自動化環境に適しています）
--auto-approve	boolean	false	ユーザーの確認なしで、破壊的な操作をすべて自動承認します（危険）
--timeout	duration	30s	リクエストのタイムアウト時間
--log-level	string	info	ログレベル（debug、info、warn、error）
--no-logs	boolean	false	監査ログを無効にします（ローカルファイルは作成されません）

フラグの詳細

--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 ツールを使用してください

環境変数

変数	型	デフォルト	説明
KSM_CONFIG_BASE64	string	""	Base64 エンコードされた KSM 設定文字列
KSM_MCP_CONFIG_DIR	string	~/.keeper/ksm-mcp	プロファイルとログのディレクトリ
KSM_MCP_PROFILE	string	""	デフォルトで使用するプロファイル名

設定の優先順位

サーバーは、次の優先順位で設定を使用します。

1. CLI フラグ --config-base64（最優先）
2. 環境変数 KSM_CONFIG_BASE64
3. ローカルのプロファイルストレージを使用する CLI フラグ --profile
4. ローカルのプロファイルストレージを使用する環境変数 KSM_MCP_PROFILE

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

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

プロファイルを使うと、機密性の高い認証情報を公開せずに、KSM の設定をローカルで安全に保存、管理できます。

• セキュリティ：Base64 形式の設定には、機密性の高い KSM アプリケーションの認証情報が含まれています。プロファイルでは、これらをパスワードで保護して暗号化し、ローカルに保存します。
• 利便性：初期化後は、毎回 Base64 形式の設定全体を渡す代わりに、プロファイル名を指定するだけで済みます。
• 複数の環境：異なる KSM アプリケーション（dev、staging、prod）を、それぞれ別のプロファイルで管理できます。
• 認証情報の保護：コマンドライン、環境変数、設定ファイルに機密データが含まれるのを防ぎます。
• 永続的な保存：システムの再起動後も保持され、認証情報を再入力する必要がありません。

プロファイルと直接設定を使い分ける方法：

• プロファイルの使用に適した用途：ローカル開発、永続的なセットアップ、複数の環境
• 直接設定の使用に適した用途：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

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

方法	セキュリティレベル	使用例
環境変数を使った Docker	高	本番環境、CI/CD
プロファイルを使ったバイナリ	高	ローカル開発、永続的なセットアップ
CLI フラグを使ったバイナリ	中	テスト、一時的な使用
環境変数を使ったバイナリ	高	本番環境、コンテナ化された環境
サイレントモード	高	コンプライアンス、ローカルにファイルを残さない場合

トラブルシューティング

よくある問題

1. 「アクティブなセッションがありません」というエラー：次のいずれかが設定されていることを確認してください。

   • 初期化済みのプロファイルを指定する有効な --profile フラグ
   • 有効な --config-base64 フラグ、または KSM_CONFIG_BASE64 環境変数

2. 「ログディレクトリの作成に失敗しました」という警告：ローカルでのログ記録を無効にするには、--no-logs フラグを使用してください。

3. アクセス許可エラー：バイナリに実行権限があり、設定ディレクトリへの書き込みが可能であることを確認してください。

デバッグモード

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

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

例

開発環境のセットアップ

# Initialize profile
ksm-mcp init --profile dev --config "ewogICJob3N0bmFtZSI6..."

# Run server
ksm-mcp serve --profile dev --log-level debug

本番環境のセットアップ（Docker）

docker run -i --rm \
  -e KSM_CONFIG_BASE64="ewogICJob3N0bmFtZSI6..." \
  keeper-mcp-server:latest

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

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