KSM MCP Server - Secure AI Access to Keeper Secrets

KSM MCP 服务 - 安全地让 AI 访问 Keeper Secrets

KSM MCP 是一种模型上下文协议（MCP）服务，可在 AI 大语言模型（如 Claude）与 Keeper Secrets Manager（KSM）之间充当安全中介。它允许 AI Agent 管理您的 KSM 密钥，例如列出、创建、获取和删除记录及文件夹，同时保护您的 KSM 应用凭据。敏感操作需要用户确认，确保您始终掌控自己的数据。

用户快速指南

选项 1：使用 Docker（推荐）

1. 获取 KSM Base64 配置：

   • 登录 Keeper Secrets Vault。
   • 前往您的 Secrets Manager，选择应用，然后转到“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",
           "keeper/keeper-mcp-server:latest"
         ]
       }
       // You might have other servers like "memory" here, leave them as is.
     }
   }
   

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"] // Use the profile name you initialized
       }
       // ... 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 的连接的运行状态。

示例用例

以下是一些 instruct AI Agent（如 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' 文件夹现在为空，请一并删除该文件夹。”

• 将配置文件上传到现有记录： “我有一个生产集群的新 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 Agent
  • 不适合手动确认的批量操作
• 推荐替代方案：使用 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 应用（开发、预发布、生产）
• 凭据保护：避免敏感数据出现在命令行、环境变量和配置文件中
• 持久存储：系统重启后仍会保留，无需重新输入凭据

何时使用配置文件，何时使用直接配置：

• 适合使用配置文件的场景：本地开发、持久化设置、多环境
• 适合使用直接配置的场景：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. “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

示例

开发环境设置

# 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