内容
# mcp-safe-run
**用于 IDE 集成 MCP 服务器的安全、零泄漏密钥，在一分钟内完成。**
mcp-safe-run 允许您启动用于 AI 驱动的 IDE（如 Cursor、Windsurf 或 Claude Desktop）的 Model Context Protocol (MCP) 服务器，使用的密钥永远不会在您的 shell、进程列表或版本控制中公开。将密钥持久存储在您的操作系统密钥链或隐藏文件中，在您的 IDE 配置中安全地引用它们，并通过单击启动服务器——无需再复制粘贴令牌或冒着意外泄漏的风险。
---
## 快速开始
1. **安装：**
```sh
npm install -g mcp-safe-run
```
2. **创建一个密钥目录：**
```sh
mkdir -p ./secrets
echo "/secrets/*" >> .gitignore
```
3. **添加您的密钥：**
```sh
echo "ghp_...TOKEN..." > ./secrets/github_token.txt
chmod 600 ./secrets/github_token.txt
```
4. **配置您的 IDE：** 将以下内容添加到您的 IDE 的 MCP 服务器设置中（例如，`mcp_settings.json`）：
```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）
要将此项目与支持 Model Context Protocol 的 IDE（如 Cursor、Windsurf 或 Claude Desktop）一起使用，请将 `mcpServers` 部分添加到您的设置中（例如 `mcp_settings.json`）。这使 IDE 能够启动具有安全环境解析的 MCP 服务器。
**配置示例：**
```json
{
"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. 为您的密钥创建一个隐藏目录（如果它不存在）：
```sh
mkdir -p ./secrets
```
2. 添加一个 `.gitignore` 规则，以防止密钥进入版本控制：
```
# .gitignore
/secrets/*
```
3. 创建您的密钥文件，例如 `./secrets/github_token.txt`，并将您的令牌或密钥值粘贴到其中。
4. 保护文件，以便只有您的用户可以读取它：
```sh
chmod 600 ./secrets/github_token.txt
```
5. 在您的配置中，使用 `file:` 占位符，例如：
```json
{ "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
```
#### 选项 2：在 macOS 上使用操作系统密钥链 (`keyring:`)
1. 打开 **Keychain Access** 应用程序（应用程序 > 实用工具 > 钥匙串访问）。
2. 单击 `+` 按钮以添加新的密码项。
3. 设置 **Keychain Item Name**（服务）和 **Account Name**（帐户）以匹配您的占位符，例如：
- 服务：`mcp-github`
- 帐户：`personal-pat`
4. 将您的密钥/令牌粘贴到“密码”字段中并保存。
5. 或者，您可以使用 `keytar` Node.js CLI 或 API 以编程方式添加密钥：
```js
// Example using keytar in Node.js
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');
```
6. 在您的配置中，使用 `keyring:` 占位符，例如：
```json
{ "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }
```
### 笔记：
- `GITHUB_TOKEN` 将使用 `keyring:` 占位符从您的操作系统密钥链安全地解析。
- 您可能需要使用 `keytar` 或您操作系统的密钥管理器等工具将密钥添加到您的密钥链。
- 此模式适用于任何 MCP 服务器；只需根据您的用例调整命令和参数即可。
- 在这些 IDE 中，通常不支持 `env:` 占位符（IDE 不传递您的 shell 环境），因此首选 `keyring:` 或 `file:` 占位符。
---
## 安装
```sh
npm install -g mcp-safe-run
```
> **注意：** 此 CLI 使用 [keytar](https://github.com/atom/node-keytar) 来支持操作系统密钥链。在 macOS 上，安装 Xcode Command Line Tools。在 Linux 上，安装 `libsecret-1-dev` 和 `build-essential`（或等效的构建工具）。在 Windows 上，安装 Visual Studio Build Tools (`npm install --global --production windows-build-tools`)。
## 用法
```sh
mcp-safe-run [options] <targetCommand> [targetArgs...]
```
### 选项
- `-V, --version` 输出当前版本。
- `-c, --config <path>` 自定义配置文件（.yaml 或 .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/mcp-safe-run/` 中的 `config.yaml` 或 `config.yml`（如果目录不存在，则创建该目录）。
**格式：**
```yaml
# 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. 从执行 `mcp-safe-run` 的 shell 继承的环境变量（最低优先级）。
## 例子
1. **使用 `--target-env`（仅限 CLI）：**
```sh
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`：*
```yaml
profiles:
github_server:
target-env:
GITHUB_TOKEN: "keyring:mcp:github"
PORT: "8080"
```
*使用配置文件运行：*
```sh
# 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. **使用特定的配置文件：**
```sh
mcp-safe-run -c ~/configs/mcp-servers.yaml -p prod_server node my_server.js
```
4. **使用 `--target-env` 覆盖配置文件：**
*假设存在 `.mcp-saferun.yaml`，其中包含示例 2 中的 `github_server` 配置文件。*
```sh
# 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. **详细模式：**
```sh
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 中使用时。
- **某些客户端（Cursor、Windsurf、Claude Desktop）中不支持的占位符 (`env:`)：** 这些环境不会将 shell 环境变量传递给 `mcp-safe-run`，因此 `env:` 占位符将无法解析。`file:` 和 `keyring:` 占位符仍然有效。例如：
```sh
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 Command Line Tools。
- **Linux：** 需要 `libsecret-1-dev` 和构建工具，如 `build-essential`。
- **Windows：** 需要 Visual Studio Build Tools（可以通过 `npm install --global --production windows-build-tools` 安装）。
---
## IDE 设置（Cursor、Windsurf、Claude Desktop）
要将此项目与支持 Model Context Protocol 的 IDE（如 Cursor、Windsurf 或 Claude Desktop）一起使用，请将 `mcpServers` 部分添加到您的设置中（例如 `mcp_settings.json`）。这使 IDE 能够启动具有安全环境解析的 MCP 服务器。
**配置示例：**
```json
{
"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. 为您的密钥创建一个隐藏目录（如果它不存在）：
```sh
mkdir -p ./secrets
```
2. 添加一个 `.gitignore` 规则，以防止密钥进入版本控制：
```
# .gitignore
/secrets/*
```
3. 创建您的密钥文件，例如 `./secrets/github_token.txt`，并将您的令牌或密钥值粘贴到其中。
4. 保护文件，以便只有您的用户可以读取它：
```sh
chmod 600 ./secrets/github_token.txt
```
5. 在您的配置中，使用 `file:` 占位符，例如：
```json
{ "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
```
#### 选项 2：在 macOS 上使用操作系统密钥链 (`keyring:`)
1. 打开 **Keychain Access** 应用程序（应用程序 > 实用工具 > 钥匙串访问）。
2. 单击 `+` 按钮以添加新的密码项。
3. 设置 **Keychain Item Name**（服务）和 **Account Name**（帐户）以匹配您的占位符，例如：
- 服务：`mcp-github`
- 帐户：`personal-pat`
4. 将您的密钥/令牌粘贴到“密码”字段中并保存。
5. 或者，您可以使用 `keytar` Node.js CLI 或 API 以编程方式添加密钥：
```js
// Example using keytar in Node.js
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');
```
6. 在您的配置中，使用 `keyring:` 占位符，例如：
```json
{ "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }
```
### 笔记：
- `GITHUB_TOKEN` 将使用 `keyring:` 占位符从您的操作系统密钥链安全地解析。
- 您可能需要使用 `keytar` 或您操作系统的密钥管理器等工具将密钥添加到您的密钥链。
- 此模式适用于任何 MCP 服务器；只需根据您的用例调整命令和参数即可。
- 在这些 IDE 中，通常不支持 `env:` 占位符（IDE 不传递您的 shell 环境），因此首选 `keyring:` 或 `file:` 占位符。
---
连接信息
猜你喜欢
暂无推荐服务器