守护者-mcp-golang-docker

Name: 守护者-mcp-golang-docker
Author: Keeper-Security

作者：Keeper-Security6 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

KSM MCP Server - 安全访问Keeper Secrets

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

快速用户指南

方案1：使用Docker（推荐）

获取KSM Base64配置：
- 登录到Keeper Secrets Vault。
- 导航至您的Secrets Manager，应用，然后转到“设备”标签。
- 点击“添加设备”，并复制提供的base64编码配置字符串（通常以ewog...开头）。
重要提示：Base64配置包含您的KSM应用程序凭证。请妥善保管，切勿提交到版本控制系统。
配置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服务器条目如下，用实际的base64配置替换YOUR_BASE64_CONFIG_STRING_HERE：
```
{
  "mcpServers": {
    "ksm": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KSM_CONFIG_BASE64=YOUR_BASE64_CONFIG_STRING_HERE",
        "keepersecurityinc/ksm-mcp-poc:latest"
      ]
    }
    // 您可能还有其他服务器如"memory"，保留它们不变。
  }
}
```
重启Claude Desktop：
- KSM服务器现在应该可以被Claude使用。首次连接时，它会使用base64配置启动。

方案2：使用预编译二进制文件

下载二进制文件：
- 前往KSM MCP Releases页面，下载适合您操作系统的二进制文件（例如，Intel Macs的ksm-mcp-darwin-amd64，Windows的ksm-mcp-windows-amd64.exe）。
- 将二进制文件设置为可执行（例如，chmod +x ./ksm-mcp-darwin-amd64），并将其放置在系统PATH中的目录中，或者记下其完整路径。
获取KSM Base64配置：（参见Docker指南中的步骤1）

重要提示：Base64配置包含您的KSM应用程序凭证。请妥善保管，切勿提交到版本控制系统。
初始化KSM MCP配置文件：
- 在终端中运行初始化命令，替换YOUR_BASE64_CONFIG_STRING并选择一个配置文件名（例如，默认）：
```
/path/to/ksm-mcp init --profile default --config "YOUR_BASE64_CONFIG_STRING"
```
- 您将被要求设置本地配置存储的保护密码。记住这个密码，因为如果您手动重启服务器或配置要求时，您需要它。对于与Claude的自动化使用，通常服务器以批处理模式运行，此时不会交互式地提示。
配置Claude Desktop：
- 打开您的claude_desktop_config.json文件（参见Docker指南中的路径）。
- 添加或更新ksm服务器条目，用实际下载的二进制文件路径替换/path/to/ksm-mcp：
```
{
  "mcpServers": {
    "ksm": {
      "command": "/path/to/ksm-mcp",
      "args": ["serve", "--profile", "default"] // 使用您初始化的配置文件名
    }
    // ... 其他服务器 ...
  }
}
```
重启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的连接。

示例用例

这里有一些示例，说明您可以如何指示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'文件夹现在为空，请一并删除该文件夹。"
将配置文件上传到现有记录： "我有一个新的Kubernetes配置文件，位于'~/Downloads/kubeconfig-prod.yaml'，用于我们的生产集群。请将此文件上传到标题为'Production K8s Cluster Access'的KSM记录，并将附件命名为'kubeconfig-prod-cluster.yaml'。"
生成安全密码并保存到新记录： "生成一个非常强的32字符密码，包括大写字母、小写字母、数字和特殊字符。直接将其保存到标题为'Internal Audit Service Account'的新登录记录中，位于'Service Accounts'文件夹内。不要向我展示密码。"
检查跨环境配置一致性： "我的服务配置记录按环境（dev、qa）组织在文件夹中，每个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：带有Base64配置的预编译二进制文件（CLI标志）

{
  "mcpServers": {
    1. "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`	字符串	`""`	使用本地存储中的配置文件名
`--config-base64`	字符串	`""`	Base64编码的KSM配置字符串
`--batch`	布尔值	`false`	运行在批处理模式（无密码提示，适用于自动化环境）
`--auto-approve`	布尔值	`false`	自动批准所有破坏性操作，无需用户确认（危险）
`--timeout`	持续时间	`30s`	请求超时持续时间
`--log-level`	字符串	`info`	日志级别（debug、info、warn、error）
`--no-logs`	布尔值	`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代理在受控场景中
- 手动确认不实用的大批量操作
推荐替代方案：使用ksm_execute_confirmed_action工具进行选择性批准

环境变量

变量	类型	默认值	描述
`KSM_CONFIG_BASE64`	字符串	`""`	Base64编码的KSM配置字符串
`KSM_MCP_CONFIG_DIR`	字符串	`~/.keeper/ksm-mcp`	配置文件和日志目录
`KSM_MCP_PROFILE`	字符串	`""`	默认配置文件名

配置优先级

服务器使用以下优先级顺序进行配置：

CLI标志--config-base64（最高优先级）
环境变量KSM_CONFIG_BASE64
**CLI标志--profile**与本地配置存储
**环境变量KSM_MCP_PROFILE**与本地配置存储

配置文件管理命令

为什么使用配置文件？

配置文件提供了一种安全的方式来本地存储和管理KSM配置，而无需暴露敏感凭证：

安全性：您的base64配置包含敏感的KSM应用程序凭证。配置文件使用密码保护加密并本地存储这些信息
便利性：初始化后，您只需引用配置文件名，而无需每次传递完整的base64配置
多环境管理：管理不同的KSM应用程序（开发、暂存、生产）使用单独的配置文件
凭证保护：将敏感数据从命令行、环境变量和配置文件中移出
持久存储：即使系统重启也能生存，无需重新输入凭证

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

使用配置文件：本地开发、持久设置、多环境
使用直接配置：CI/CD、Docker容器、临时使用、不希望本地存储的环境

初始化新配置文件

ksm-mcp init --profile PROFILE_NAME --config "BASE64_CONFIG_STRING"

此命令：

接收您的base64 KSM配置
使用您提供的密码对其进行加密
存储在本地~/.keeper/ksm-mcp/profiles/
未来使用只需--profile PROFILE_NAME

列出可用配置文件

ksm-mcp profiles list

删除配置文件

ksm-mcp profiles delete --profile PROFILE_NAME

安全考虑

方法	安全等级	使用案例
Docker与环境变量	高	生产、CI/CD
二进制文件与配置文件	高	本地开发、持久设置
二进制文件与CLI标志	中	测试、临时使用
二进制文件与环境变量	高	生产、容器化环境
静默模式	高	遵守合规性、无本地工件

故障排除

常见问题

"No active session"错误：确保您有：
- 有效的--profile标志指向已初始化的配置文件
- 有效的--config-base64标志或KSM_CONFIG_BASE64环境变量
"Failed to create log directory"警告：使用--no-logs标志禁用本地日志
权限拒绝错误：确保二进制文件具有执行权限，且配置目录可写

调试模式

启用调试日志以进行故障排除：

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