MCP安全运行服务器

Name: MCP安全运行服务器
Author: ithena-one

作者：ithena-one12 星标更新：2025-04-20

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

项目介绍

mcp-safe-run

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

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

快速开始

安装：
```
npm install -g mcp-safe-run
```

创建一个秘密目录：

mkdir -p ./secrets
echo "/secrets/*" >> .gitignore

添加您的秘密：

echo "ghp_...TOKEN..." > ./secrets/github_token.txt
chmod 600 ./secrets/github_token.txt

配置您的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": {}
    }
  }
}

从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:`）

创建一个隐藏的秘密目录（如果不存在）：
```
mkdir -p ./secrets
```
添加一个.gitignore规则以防止秘密进入版本控制：
```
# .gitignore
/secrets/*
```
创建您的秘密文件，例如./secrets/github_token.txt，并将您的令牌或秘密值粘贴进去。
将文件权限设置为仅允许您的用户读取：
```
chmod 600 ./secrets/github_token.txt
```
在您的配置中使用一个file:占位符，例如：
```
{ "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
```

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

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

或者，您可以使用keytarNode.js CLI或API程序化地添加秘密：

// 使用Node.js中的keytar示例
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');

在您的配置中使用一个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标志可能比管理单独的配置文件更简单。配置文件的主要好处在于管理同一目标命令的多个不同配置（配置文件）。

搜索顺序：

由-c, --config <路径>指定的路径。
当前工作目录中的.mcp-saferun.yaml或.mcp-saferun.yml。
~/.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:
#   设置: 值

优先级：

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

示例

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

使用配置文件配置文件：

在项目中创建.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作为其环境变量

使用特定配置文件：

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

使用--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。

详细模式：

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）

示例配置：

{
  "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:`）

创建一个隐藏的秘密目录（如果不存在）：
```
mkdir -p ./secrets
```
添加一个.gitignore规则以防止秘密进入版本控制：
```
# .gitignore
/secrets/*
```
创建您的秘密文件，例如./secrets/github_token.txt，并将您的令牌或秘密值粘贴进去。
将文件权限设置为仅允许您的用户读取：
```
chmod [权限] ./secrets/github_token.txt
```
在您的配置中使用一个file:占位符，例如：
```
{ "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
```

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

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

或者，您可以使用keytarNode.js CLI或API程序化地添加秘密：

// 使用Node.js中的keytar示例
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');

在您的配置中使用一个keyring:占位符，例如：
```
{ "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }
```

注意事项：

GITHUB_TOKEN将通过keyring:占位符从您的操作系统密钥链中安全解析。
您可能需要使用像keytar这样的工具或操作系统的秘密管理器将秘密添加到您的密钥链中。
这种模式适用于任何MCP服务器；只需根据您的需求调整命令和参数即可。
在这些IDE中，env:占位符通常不受支持（IDE不会传递您的shell环境），因此建议使用keyring:或file:占位符。

MCP安全运行服务器

项目介绍

mcp-safe-run

快速开始

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

为IDE集成设置秘密

方案1：使用密钥文件（file:）

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

注意事项：

安装

使用

选项

占位符语法

配置文件

示例

故障排除

平台说明

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

为IDE集成设置秘密

方案1：使用密钥文件（file:）

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

注意事项：

方案1：使用密钥文件（`file:`）

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

方案1：使用密钥文件（`file:`）

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