mcp-safe-run

在不到一分钟内为集成IDE的MCP服务器提供安全且无泄露的秘密。

mcp-safe-run 允许您使用从不暴露于您的shell、进程列表或版本控制中的秘密来启动用于AI驱动IDE（如Cursor、Windsurf或Claude Desktop）的模型上下文协议（MCP）服务器。持久地将秘密存储在您的操作系统密钥链或隐藏文件中，在IDE配置中安全引用它们，并通过单击启动服务器——无需复制粘贴令牌或冒险意外泄露。

---

快速开始

1. 安装：

   npm install -g mcp-safe-run
   

2. 创建一个秘密目录：

   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的设置（Cursor、Windsurf、Claude Desktop）

要使用支持模型上下文协议（如Cursor、Windsurf或Claude Desktop）的IDE，需在设置中添加一个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. 添加一个.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. 设置钥匙串项目名称（服务）和账户名称（账户），使其与您的占位符匹配，例如：
   • 服务：mcp-github
   • 账户：personal-pat
4. 将您的秘密/令牌粘贴到“密码”字段中并保存。
5. 或者，您可以使用keytarNode.js CLI或API程序化地添加秘密：

   // 使用Node.js中的keytar示例
   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使用keytar支持操作系统密钥链。在macOS上，安装Xcode命令行工具。在Linux上，安装libsecret-1-dev和build-essential（或等效构建工具）。在Windows上，安装Visual Studio构建工具（npm install --global --production windows-build-tools）。

使用

mcp-safe-run [选项] <目标命令> [目标参数...]

选项

• -V, --version 输出当前版本。
• -c, --config <路径> 自定义配置文件的路径（.yaml或.yml）。
• -p, --profile <名称> 从配置文件中使用的配置文件名称。
• --target-env <json字符串> 目标环境变量的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 <路径>指定的路径。
2. 当前工作目录中的.mcp-saferun.yaml或.mcp-saferun.yml。
3. ~/.config/mcp-safe-run/内的config.yaml或config.yml（如果该目录不存在，则会创建）。

格式：

# 示例 .mcp-saferun.yaml
profiles:
  # 配置文件名称（使用 -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:
#   设置: 值

优先级：

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

示例

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"
   

   使用配置文件运行：

   # 确保密钥链条目存在：
   # keytar set mcp github ghp_...TOKEN...
   
   mcp-safe-run -p github_server npx -y @modelcontextprotocol/server-github
   # 目标命令将接收GITHUB_TOKEN和PORT作为其环境变量
   

3. 使用特定配置文件：

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

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

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

   # 临时覆盖配置文件中定义的PORT
   mcp-safe-run -p github_server --target-env '{"PORT":"9000"}' \
     npx -y @modelcontextprotocol/server-github
   # GITHUB_TOKEN来自配置文件（密钥链），但PORT由CLI标志设置为9000。
   

5. 详细模式：

   mcp-safe-run -v -p github_server npx -y @modelcontextprotocol/server-github
   # 显示配置加载、解析值（如果启用详细模式）、最终环境等。
   

故障排除

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

• 未找到配置文件： 验证使用-p的配置文件名称是否存在于加载的配置文件中。

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

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

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

• keytar构建/运行时问题： 查看平台说明并确保安装必要的构建工具/库。

• 无效JSON（--target-env）： 确保正确引用，特别是在shell中使用时。

• 某些客户端（Cursor、Windsurf、Claude Desktop）不支持的占位符（env:）： 这些环境不会将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"}' <目标命令> [参数...]
  

平台说明

• macOS： 需要Xcode命令行工具。
• Linux： 需要libsecret-1-dev和构建工具如build-essential。
• Windows： 需要Visual Studio构建工具（可以通过npm install --global --production windows-build-tools安装）。

---

集成IDE的设置（Cursor、Windsurf、Claude Desktop）

要使用支持模型上下文协议（如Cursor、Windsurf或Claude Desktop）的IDE，需在设置中添加一个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. 添加一个.gitignore规则以防止秘密进入版本控制：

   # .gitignore
   /secrets/*
   

3. 创建您的秘密文件，例如./secrets/github_token.txt，并将您的令牌或秘密值粘贴进去。
4. 将文件权限设置为仅允许您的用户读取：

   chmod [权限] ./secrets/github_token.txt
   

5. 在您的配置中使用一个file:占位符，例如：

   { "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
   

方案2：使用操作系统密钥链（keyring:）在macOS上

1. 打开钥匙串访问应用（应用程序 > 实用工具 > 钥匙串访问）。
2. 单击+按钮添加一个新的密码项。
3. 设置钥匙串项目名称（服务）和账户名称（账户），使其与您的占位符匹配，例如：
   • 服务：mcp-github
   • 账户：personal-pat
4. 将您的秘密/令牌粘贴到“密码”字段中并保存。
5. 或者，您可以使用keytarNode.js CLI或API程序化地添加秘密：

   // 使用Node.js中的keytar示例
   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:占位符。