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

KSM MCP 是一个模型上下文协议 (MCP) 服务器，充当 AI 语言模型（如 Claude）与 Keeper Secrets Manager (KSM) 之间的安全中介。它允许 AI 代理管理您的 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：

   • 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 配置文件：

   • 打开终端并运行初始化命令，替换 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 替换为您下载的二进制文件的实际路径： GXP3

5. 重启 Claude Desktop。

Related MCP server: keyshade-mcp

功能（可用工具）

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 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' 的新登录记录中。不要向我显示密码。”

• 检查跨环境的配置一致性： “我有按环境（开发、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 标志完全禁用审计日志记录，确保不创建任何本地文件。这适用于：

• 必须避免创建本地文件的合规环境

• 不需要持久性的容器化部署

• 临时或测试场景

• 具有只读文件系统的系统

命令行标志

标志详情

--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

示例

开发设置

# 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