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