KSM MCP服务器

KSM MCP服务器-安全的AI访问Keeper机密

KSM MCP是一个模型上下文协议（MCP）服务器，充当AI语言模型（如Claude）和Keeper Secrets Manager（KSM）之间的安全中介。它允许AI代理管理您的KSM机密，如列出、创建、检索和删除记录和文件夹，同时保护您的KSM应用程序凭据。敏感操作需要用户确认，以确保您对数据保持控制。

快速用户指南

选项1：使用Docker（推荐）

1. 获取KSM Base64配置：

   • 登录 Keeper秘密库.
   • 导航到您的秘密管理器、应用程序，然后导航到“设备”选项卡。
   • 点击“添加设备”并复制 base64编码配置字符串 提供（通常以 ewog...).

   重要：base64配置包含KSM应用程序的凭据。确保其安全，切勿将其提交给版本控制。

2. 配置Claude桌面：

   • 打开您的Claude Desktop配置文件：
     • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
     • 窗户： %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应该可以使用KSM服务器了。第一次连接时，它将使用base64配置启动。

选项2：使用预编译二进制文件

1. 下载二进制文件：

   • 去 KSM MCP发布页面 并下载适用于您的操作系统的适当二进制文件（例如。， ksm-mcp-darwin-amd64 对于Intel Mac， ksm-mcp-windows-amd64.exe 适用于Windows）。
   • 使二进制文件可执行（例如。， 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桌面：

   • 打开你的 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. 重新启动克劳德桌面。

功能（可用工具）

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-RERCDS”共享文件夹下创建一个名为“Project Phoenix Shared”的新文件夹。然后，在“Project Phoenix-Shared”中，使用用户名“Phoenix_user”、密码“ComplexP@$$wOrd123！”和URL“DB.fenix.Dev.internal”创建一个标题为“Phoenix Dev DB”的新登录密码。”

• 列出秘密并检索一个： 列出“API密钥”文件夹中的所有机密。然后，获取标题为“Third-Party Analytics API密钥”的机密的详细信息，但保持API密钥本身隐藏

• 删除机密，然后删除其文件夹（如果为空）： 删除名为“旧暂存服务器凭据”的机密。完成此操作后，如果它所在的“暂存环境”文件夹现在为空，请同时删除该文件夹

• 将配置文件上传到现有记录： “我在‘~/Downloads/kubeconfig-prod.yaml’为我们的生产集群创建了一个新的Kubernetes配置文件。请将此文件上传到标题为‘production K8s cluster Access’的KSM记录中，并将附件命名为‘kubeconfig-prod cluster.yaml’。”

• 生成安全密码并将其保存到新记录中： 生成一个包含大小写、数字和特殊字符的32个字符的强密码。将其直接保存到“服务帐户”文件夹中名为“内部审核服务帐户”的新登录记录中。不要向我显示密码

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

• 必须避免创建本地文件的合规性环境
• 不需要持久性的容器化部署
• 临时或测试场景
• 具有只读文件系统的系统

命令行标志

标志详细信息

--batch （非交互模式）

• 目的：防止服务器提示输入密码或用户输入
• 何时使用:
  • 自动化环境（CI/CD、Docker容器）
  • 当作为服务运行时，无法进行人工交互
  • Claude桌面集成（推荐）
• 它做什么:
  • 加载加密配置文件时跳过密码提示
  • 对所有配置使用环境变量或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. “无活动会话”错误：确保您有：

   • A有效 --profile 指向已初始化配置文件的标志
   • A有效 --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