AI导哈

安全密钥管理工具

mcp-safe-run 是一款用于安全管理和使用密钥的工具，特别适用于集成开发环境（IDE）中的Model Context Protocol（MCP）服务器，确保密钥不会在shell、进程列表或版本控制中泄露。

  • by ithena-one
  • TypeScript
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 ithena-one/mcp-safe-run

使用说明

mcp安全运行

在不到一分钟的时间内为集成IDE的MCP服务器提供安全、零泄漏的秘密。

mcp安全运行允许您使用从未在shell、进程列表或版本控制中公开的秘密来启动AI驱动的IDE（如Cursor、Windsurf或Claude Desktop）的模型上下文协议（mcp）服务器。将机密持久地存储在操作系统密钥链或隐藏文件中，在IDE配置中安全地引用它们，并一键启动服务器——不再复制粘贴令牌或冒意外泄漏的风险。

快速开始

  1. 安装：
    npm install -g mcp-safe-run
  2. 创建secrets目录：
    mkdir -p ./secrets
echo "/secrets/*" >> .gitignore
  3. 添加您的密码：
    echo "ghp_...TOKEN..." > ./secrets/github_token.txt
chmod 600 ./secrets/github_token.txt
  4. 配置IDE： 将以下内容添加到IDE的MCP服务器设置中（例如。， mcp_settings.json):
    {
  "mcpServers": {
    "github": {
      "command": "mcp-safe-run",
      "args": [
        "--target-env",
        "{\"GITHUB_TOKEN\": \"file:./secrets/github_token.txt\"}",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {}
    }
  }
}
  5. 从IDE启动服务器。

IDE设置（光标、风帆、克劳德桌面）

要将此项目与支持模型上下文协议的IDE（如Cursor、Windsurf或Claude Desktop）一起使用，请添加 mcpServers 将部分添加到您的设置中（例如 mcp_settings.json).这使得IDE能够以安全的环境分辨率启动MCP服务器。

配置示例：

{
  "mcpServers": {
    "github": {
      "command": "mcp-safe-run",
      "args": [
        "--target-env",
        "{\"GITHUB_TOKEN\": \"keyring:mcp-github:personal-pat\"}",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {}
    }
  }
}

为IDE集成设置秘密

选项1：使用密钥文件(file:)

  1. 为你的秘密创建一个隐藏目录（如果它不存在）：
    mkdir -p ./secrets
  2. 添加a .gitignore 将机密排除在版本控制之外的规则：
    # .gitignore
/secrets/*
  3. 创建您的机密文件，例如。 ./secrets/github_token.txt，并将您的令牌或秘密值粘贴到其中。
  4. 保护文件，以便只有您的用户可以读取它：
    chmod 600 ./secrets/github_token.txt
  5. 在您的配置中，使用 file: 占位符，例如：
    { "GITHUB_TOKEN": "file:./secrets/github_token.txt" }

选项2：使用操作系统钥匙链(keyring:在macOS

  1. 打开 钥匙串访问 应用程序（应用程序>实用程序>钥匙链访问）。
  2. 点击 + 按钮添加新密码项。
  3. 设置 钥匙扣项目名称 （服务）和 账户名称 （account）匹配您的占位符，例如：
    • 服务： mcp-github
    • 账户 personal-pat
  4. 将您的秘密/令牌粘贴到“密码”字段并保存。
  5. 或者，您可以使用 keytar Node.js CLI或API以编程方式添加机密：
    // Example using keytar in Node.js
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');
  6. 在您的配置中，使用 keyring: 占位符，例如：
    { "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }

笔记：

  • 这 GITHUB_TOKEN 将使用 keyring: 占位符。
  • 您可能需要使用以下工具将密钥添加到密钥链中 keytar 或者操作系统的秘密管理器。
  • 此模式适用于任何MCP服务器；只需根据用例的需要调整命令和参数。
  • 在这些IDE中， env: 占位符通常不受支持（IDE不通过您的shell环境），因此更喜欢 keyring: 或 file: 占位符。

安装

npm install -g mcp-safe-run

注： 此CLI使用 肩背式键盘 用于操作系统钥匙链支持。在macOS上，安装Xcode命令行工具。在Linux上，安装 libsecret-1-dev 和 build-essential （或等效的构建工具）。在Windows上，安装Visual Studio生成工具(npm install --global --production windows-build-tools).

用法

mcp-safe-run [options] <targetCommand> [targetArgs...]

选项

  • -V, --version 输出当前版本。
  • -c, --config <path> 自定义配置文件（.yml或.yml）的路径。
  • -p, --profile <name> 配置文件中要使用的配置文件的名称。
  • --target-env <jsonString> 目标环境变量的JSON映射。 覆盖配置文件配置文件设置。
  • -v, --verbose 启用详细日志记录（输出诊断详细信息）。
  • -h, --help 显示帮助信息。

占位符语法

占位符可用于 --target-env JSON字符串或 target-env 配置文件配置文件的一部分。

  • env:VAR_NAME 使用环境变量的值 VAR_NAME.
  • file:/path/to/file 读取并修剪指定文件的内容（支持 ~ 主目录）。
  • keyring:service:account 使用指定的密钥从操作系统密钥链中检索密钥 service 和 account.
  • 文字值 任何其他字符串都将原封不动地传递。

配置文件

为了管理多个配置，您可以使用YAML配置文件（例如。， .mcp-saferun.yaml 或 .mcp-saferun.yml).当您需要频繁地在不同的环境变量集之间切换时，这尤其有用，例如对于不同的部署环境（开发、测试、生产）或不同的操作上下文。

使用环境说明： 对于更简单的场景，例如在IDE集成中配置单个MCP服务器（例如，通过 mcp.json)，使用 --target-env 直接标记可能比管理单独的配置文件更简单。配置文件的主要好处在于管理多个不同的配置（配置文件） 相同 目标命令。

搜索顺序：

  1. 指定的路径 -c, --config <path>.
  2. .mcp-saferun.yaml 或 .mcp-saferun.yml 在当前工作目录中。
  3. config.yaml 或 config.yml 内部 ~/.config/mcp-safe-run/ （如果目录不存在，则创建该目录）。

格式：

# Example .mcp-saferun.yaml
profiles:
  # Profile name (used with -p dev)
  dev:
    target-env:
      API_KEY: "env:DEV_API_KEY"
      SECRET: "keyring:my-service:dev-user"
      DB_URL: "postgresql://localhost/dev_db"

  staging:
    target-env:
      API_KEY: "file:./staging-key.txt"
      SECRET: "keyring:my-service:staging-user"
      DB_URL: "env:STAGING_DB_URL"

# Global settings can be added here if needed in the future
# global:
#   setting: value

优先：

  1. 通过提供的环境变量 --target-env （最高优先级）。
  2. 所选配置文件中定义的环境变量(-p <name>)从配置文件中。
  3. 从shell继承的环境变量 mcp-safe-run 执行（最低优先级）。

例子

  1. 使用 --target-env （仅限CLI）：

    export GH_TOKEN_FOR_MCP=ghp_...TOKEN...
mcp-safe-run --target-env '{"GITHUB_TOKEN":"env:GH_TOKEN_FOR_MCP", "OTHER_VAR":"literal_value"}' \
  npx -y @modelcontextprotocol/server-github --port 8080

  2. 使用配置文件配置文件：

    创建 .mcp-saferun.yaml 在您的项目中：

    profiles:
  github_server:
    target-env:
      GITHUB_TOKEN: "keyring:mcp:github"
      PORT: "8080"

    使用配置文件运行：

    # Make sure the keychain entry exists:
# keytar set mcp github ghp_...TOKEN...

mcp-safe-run -p github_server npx -y @modelcontextprotocol/server-github
# The target command will receive GITHUB_TOKEN and PORT in its environment

  3. 使用特定的配置文件：

    mcp-safe-run -c ~/configs/mcp-servers.yaml -p prod_server node my_server.js

  4. 使用覆盖配置文件 --target-env:

    假设 .mcp-saferun.yaml 存在于 github_server 示例2中的配置文件。

    # Temporarily override the PORT defined in the profile
mcp-safe-run -p github_server --target-env '{"PORT":"9000"}' \
  npx -y @modelcontextprotocol/server-github
# GITHUB_TOKEN comes from the profile (keyring), but PORT is set to 9000 by the CLI flag.

  5. 详细模式：

    mcp-safe-run -v -p github_server npx -y @modelcontextprotocol/server-github
# Shows config loading, resolved values (if verbose), final environment, etc.

故障排除

  • 未找到配置文件： 检查搜索路径和文件名(.mcp-saferun.yaml/.yml).确保路径正确 -c。检查权限。

  • 未找到配置文件： 验证与一起使用的配置文件名称 -p 已加载的配置文件中存在。

  • YAML错误： 确保配置文件是有效的YAML。如果不确定，请使用在线验证器。

  • 占位符错误： (env:, file:, keyring:)

    • env:：检查环境变量是否实际设置(echo $VAR_NAME).
    • file:：检查文件路径（包括 ~ 扩展），权限(ls -l)，和内容(cat).
    • keyring:：验证密码是否存在于操作系统密钥链中（使用操作系统工具或 keytar CLI（如果已安装）。确保 keytar 前提条件已满足。

  • keytar 构建/运行时问题： 检查下面的平台注释，并确保安装了必要的构建工具/库。

  • JSON无效(--target-env): 确保正确引用，尤其是在shell中使用时。

  • 不支持的占位符(env:)在某些客户端（Cursor、Windsurf、Claude Desktop）中： 这些环境不会将shell环境变量传递给 mcp-safe-run，所以 env: 占位符无法解析。 file: 和 keyring: 占位符仍然有效。例如：

    mcp-safe-run --target-env '{"API_KEY":"file:./api_key.txt","SECRET":"keyring:my-service:account","DB_URL":"file:./db_url.txt"}' <targetCommand> [args...]

平台说明

  • macOS： 需要Xcode命令行工具。
  • Linux： 需要 libsecret-1-dev 并构建以下工具 build-essential.
  • 窗户： 需要Visual Studio生成工具（可以通过安装 npm install --global --production windows-build-tools).

IDE设置（光标、风帆、克劳德桌面）

要将此项目与支持模型上下文协议的IDE（如Cursor、Windsurf或Claude Desktop）一起使用，请添加 mcpServers 将部分添加到您的设置中（例如 mcp_settings.json).这使得IDE能够以安全的环境分辨率启动MCP服务器。

配置示例：

{
  "mcpServers": {
    "github": {
      "command": "mcp-safe-run",
      "args": [
        "--target-env",
        "{\"GITHUB_TOKEN\": \"keyring:mcp-github:personal-pat\"}",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {}
    }
  }
}

为IDE集成设置秘密

选项1：使用密钥文件(file:)

  1. 为你的秘密创建一个隐藏目录（如果它不存在）：
    mkdir -p ./secrets
  2. 添加a .gitignore 将机密排除在版本控制之外的规则：
    # .gitignore
/secrets/*
  3. 创建您的机密文件，例如。 ./secrets/github_token.txt，并将您的令牌或秘密值粘贴到其中。
  4. 保护文件，以便只有您的用户可以读取它：
    chmod 600 ./secrets/github_token.txt
  5. 在您的配置中，使用 file: 占位符，例如：
    { "GITHUB_TOKEN": "file:./secrets/github_token.txt" }

选项2：使用操作系统钥匙链(keyring:在macOS

  1. 打开 钥匙串访问 应用程序（应用程序>实用程序>钥匙链访问）。
  2. 点击 + 按钮添加新密码项。
  3. 设置 钥匙扣项目名称 （服务）和 账户名称 （account）匹配您的占位符，例如：
    • 服务： mcp-github
    • 账户 personal-pat
  4. 将您的秘密/令牌粘贴到“密码”字段并保存。
  5. 或者，您可以使用 keytar Node.js CLI或API以编程方式添加机密：
    // Example using keytar in Node.js
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');
  6. 在您的配置中，使用 keyring: 占位符，例如：
    { "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }

笔记：

  • 这 GITHUB_TOKEN 将使用 keyring: 占位符。
  • 您可能需要使用以下工具将密钥添加到密钥链中 keytar 或者操作系统的秘密管理器。
  • 此模式适用于任何MCP服务器；只需根据用例的需要调整命令和参数。
  • 在这些IDE中， env: 占位符通常不受支持（IDE不通过您的shell环境），因此更喜欢 keyring: 或 file: 占位符。

相关 MCP