Keeper MCP Golang Docker

🚀 KSM MCP Server - 安全訪問 Keeper 密鑰管理系統的 AI 接口

KSM MCP 是一個模型上下文協議（MCP）服務器，它在 AI 語言模型（如 Claude）和 Keeper 密鑰管理系統（KSM）之間充當安全中介。它允許 AI 代理管理你的 KSM 密鑰，如列出、創建、檢索和刪除記錄及文件夾，同時保護你的 KSM 應用程序憑證。敏感操作需要用戶確認，確保你對數據保持控制。

🚀 快速開始

選項 1：使用 Docker（推薦）

1. 獲取 KSM Base64 配置：

   • 登錄 Keeper 密鑰庫。
   • 導航到你的密鑰管理系統、應用程序，然後點擊“設備”選項卡。
   • 點擊“添加設備”，並複製提供的 Base64 編碼配置字符串（通常以 ewog... 開頭）。

   ⚠️ 重要提示

   Base64 配置包含你的 KSM 應用程序憑證。請妥善保管，切勿提交到版本控制中。

2. 配置 Claude 桌面應用：

   • 打開你的 Claude 桌面配置文件：
     • 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 桌面應用：

   • KSM 服務器現在應該可供 Claude 使用。首次連接時，它將使用 Base64 配置啟動。

選項 2：使用預編譯二進制文件

1. 下載二進制文件：

   • 訪問 KSM MCP 發佈頁面，下載適合你操作系統的二進制文件（例如，適用於英特爾 Mac 的 ksm-mcp-darwin-amd64，適用於 Windows 的 ksm-mcp-windows-amd64.exe）。
   • 使二進制文件可執行（例如，chmod +x ./ksm-mcp-darwin-amd64），並將其放置在系統路徑包含的目錄中，或記錄其完整路徑。

2. 獲取 KSM Base64 配置：（請參閱上述 Docker 指南中的步驟 1）

   ⚠️ 重要提示

   Base64 配置包含你的 KSM 應用程序憑證。請妥善保管，切勿提交到版本控制中。

3. 初始化 KSM MCP 配置文件：

   • 打開終端並運行初始化命令，將 YOUR_BASE64_CONFIG_STRING 替換為實際值，並選擇一個配置文件名稱（例如，default）：

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

   • 系統將提示你為本地配置文件存儲設置保護密碼。請記住此密碼，因為如果你手動重啟服務器或服務器配置為需要此密碼時，你將需要它。對於與 Claude 的自動化使用，通常服務器以批量模式運行，不會交互式提示輸入此密碼。

4. 配置 Claude 桌面應用：

   • 打開你的 claude_desktop_config.json 文件（請參閱 Docker 指南中的路徑）。
   • 添加或更新 ksm 服務器條目，將 /path/to/ksm-mcp 替換為你下載的二進制文件的實際路徑：

   {
     "mcpServers": {
       "ksm": {
         "command": "/path/to/ksm-mcp",
         "args": ["serve", "--profile", "default"] // 使用你初始化的配置文件名稱
       }
       // ... 其他服務器 ...
     }
   }
   

5. 重啟 Claude 桌面應用。

✨ 主要特性

密鑰操作

• 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 Dev DB'，用戶名是 'phoenix_user'，密碼是 'ComplexP@$$wOrd123!'，URL 是 'db.phoenix.dev.internal'。”

• 列出密鑰並檢索一個： “列出 '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' 的新登錄記錄中。不要向我顯示密碼。”

• 檢查不同環境間的配置一致性： “我按環境（開發、測試）組織了服務配置記錄，併為每個 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：使用 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 桌面集成（推薦）
• 作用：
  • 加載加密配置文件時跳過密碼提示
  • 使用環境變量或 CLI 標誌進行所有配置
  • 如果缺少必需輸入，將優雅失敗，而不是掛起

--no-logs（靜默模式）

• 目的：完全禁用審計日誌記錄，防止創建任何本地文件
• 使用場景：
  • 必須避免本地工件的合規性環境
  • 容器化或臨時部署
  • 只讀文件系統環境
  • 清理很重要的測試場景
• 作用：
  • 防止創建 ~/.keeper/ksm-mcp/logs/ 目錄
  • 禁用所有審計日誌記錄（訪問日誌、錯誤日誌、系統日誌）
  • 保持完整的 MCP 功能，而無日誌記錄開銷
  • 所有日誌記錄調用使用空檢查包裝器進行安全操作
• 安全性：高 - 無敏感數據寫入本地文件

--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. 權限被拒絕錯誤：確保二進制文件具有執行權限，並且配置目錄可寫

調試模式

啟用調試日誌進行故障排除：

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