Content
# mcp-safe-run
**Secure, zero-leak secrets for IDE-integrated MCP servers in under a minute.**
mcp-safe-run lets you launch Model Context Protocol (MCP) servers for AI-powered IDEs (like Cursor, Windsurf, or Claude Desktop) using secrets that are never exposed in your shell, process list, or version control. Store secrets persistently in your OS keychain or a hidden file, reference them safely in your IDE config, and launch servers with a single click—no more copy-pasting tokens or risking accidental leaks.
---
## Quick Start
1. **Install:**
```sh
npm install -g mcp-safe-run
```
2. **Create a secrets directory:**
```sh
mkdir -p ./secrets
echo "/secrets/*" >> .gitignore
```
3. **Add your secret:**
```sh
echo "ghp_...TOKEN..." > ./secrets/github_token.txt
chmod 600 ./secrets/github_token.txt
```
4. **Configure your IDE:** Add the following to your IDE's MCP server settings (e.g., `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. **Launch the server from your IDE.**
---
## Setup for IDEs (Cursor, Windsurf, Claude Desktop)
To use this project with an IDE that supports Model Context Protocol (like Cursor, Windsurf, or Claude Desktop), add an `mcpServers` section to your settings (such as `mcp_settings.json`). This enables the IDE to launch the MCP server with secure environment resolution.
**Example configuration:**
```json
{
"mcpServers": {
"github": {
"command": "mcp-safe-run",
"args": [
"--target-env",
"{\"GITHUB_TOKEN\": \"keyring:mcp-github:personal-pat\"}",
"--",
"npx",
"-y",
"@modelcontextprotocol/server-github"
],
"env": {}
}
}
}
```
### Setting Up Secrets for IDE Integration
#### Option 1: Using a Key File (`file:`)
1. Create a hidden directory for your secrets (if it doesn't exist):
```sh
mkdir -p ./secrets
```
2. Add a `.gitignore` rule to keep secrets out of version control:
```
# .gitignore
/secrets/*
```
3. Create your secret file, e.g. `./secrets/github_token.txt`, and paste your token or secret value inside.
4. Secure the file so only your user can read it:
```sh
chmod 600 ./secrets/github_token.txt
```
5. In your configuration, use a `file:` placeholder, e.g.:
```json
{ "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
```
#### Option 2: Using the OS Keychain (`keyring:`) on macOS
1. Open the **Keychain Access** app (Applications > Utilities > Keychain Access).
2. Click the `+` button to add a new password item.
3. Set the **Keychain Item Name** (service) and **Account Name** (account) to match your placeholder, for example:
- Service: `mcp-github`
- Account: `personal-pat`
4. Paste your secret/token into the "Password" field and save.
5. Alternatively, you can use the `keytar` Node.js CLI or API to add secrets programmatically:
```js
// Example using keytar in Node.js
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');
```
6. In your configuration, use a `keyring:` placeholder, e.g.:
```json
{ "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }
```
### Notes:
- The `GITHUB_TOKEN` will be securely resolved from your OS keychain using the `keyring:` placeholder.
- You may need to add the secret to your keychain using a tool like `keytar` or your OS's secret manager.
- This pattern works for any MCP server; just adjust the command and arguments as needed for your use case.
- In these IDEs, `env:` placeholders are generally not supported (the IDE does not pass your shell environment), so prefer `keyring:` or `file:` placeholders.
---
## Installation
```sh
npm install -g mcp-safe-run
```
> **Note:** This CLI uses [keytar](https://github.com/atom/node-keytar) for OS keychain support. On macOS, install Xcode Command Line Tools. On Linux, install `libsecret-1-dev` and `build-essential` (or equivalent build tools). On Windows, install Visual Studio Build Tools (`npm install --global --production windows-build-tools`).
## Usage
```sh
mcp-safe-run [options] <targetCommand> [targetArgs...]
```
### Options
- `-V, --version` Output the current version.
- `-c, --config <path>` Path to a custom configuration file (.yaml or .yml).
- `-p, --profile <name>` Name of the profile to use from the configuration file.
- `--target-env <jsonString>` JSON mapping of target environment variables. **Overrides config file profile settings.**
- `-v, --verbose` Enable verbose logging (outputs diagnostic details).
- `-h, --help` Display help information.
### Placeholder Syntax
Placeholders can be used within the `--target-env` JSON string or in the `target-env` section of a configuration file profile.
- `env:VAR_NAME` Use the value of environment variable `VAR_NAME`.
- `file:/path/to/file` Read and trim the contents of the specified file (supports `~` for home directory).
- `keyring:service:account` Retrieve a secret from the OS keychain using the specified `service` and `account`.
- *Literal values* Any other string is passed through unchanged.
## Configuration File
For managing multiple configurations, you can use a YAML configuration file (e.g., `.mcp-saferun.yaml` or `.mcp-saferun.yml`). This is particularly useful when you need to switch between different sets of environment variables frequently, such as for different deployment environments (dev, staging, production) or distinct operational contexts.
**Note on Usage Context:** For simpler scenarios, like configuring a single MCP server within an IDE integration (e.g., via `mcp.json`), using the `--target-env` flag directly might be more straightforward than managing a separate configuration file. The primary benefit of configuration files comes when managing multiple distinct configurations (profiles) for the *same* target command.
**Search Order:**
1. Path specified by `-c, --config <path>`.
2. `.mcp-saferun.yaml` or `.mcp-saferun.yml` in the current working directory.
3. `config.yaml` or `config.yml` inside `~/.config/mcp-safe-run/` (the directory is created if it doesn't exist).
**Format:**
```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
```
**Precedence:**
1. Environment variables provided via `--target-env` (highest precedence).
2. Environment variables defined in the selected profile (`-p <name>`) from the configuration file.
3. Environment variables inherited from the shell where `mcp-safe-run` is executed (lowest precedence).
## Examples
1. **Using `--target-env` (CLI only):**
```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. **Using a Config File Profile:**
*Create `.mcp-saferun.yaml` in your project:*
```yaml
profiles:
github_server:
target-env:
GITHUB_TOKEN: "keyring:mcp:github"
PORT: "8080"
```
*Run using the profile:*
```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. **Using a Specific Config File:**
```sh
mcp-safe-run -c ~/configs/mcp-servers.yaml -p prod_server node my_server.js
```
4. **Overriding a Config Profile with `--target-env`:**
*Assume `.mcp-saferun.yaml` exists with the `github_server` profile from example 2.*
```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. **Verbose Mode:**
```sh
mcp-safe-run -v -p github_server npx -y @modelcontextprotocol/server-github
# Shows config loading, resolved values (if verbose), final environment, etc.
```
## Troubleshooting
- **Config File Not Found:** Check search paths and file names (`.mcp-saferun.yaml`/`.yml`). Ensure correct path with `-c`. Check permissions.
- **Profile Not Found:** Verify the profile name used with `-p` exists in the loaded config file.
- **YAML Errors:** Ensure the config file is valid YAML. Use an online validator if unsure.
- **Placeholder Errors:** (`env:`, `file:`, `keyring:`)
- **`env:`**: Check if the environment variable is actually set (`echo $VAR_NAME`).
- **`file:`**: Check file path (including `~` expansion), permissions (`ls -l`), and content (`cat`).
- **`keyring:`**: Verify the secret exists in the OS keychain (use OS tools or `keytar` CLI if installed). Ensure `keytar` prerequisites are met.
- **`keytar` Build/Runtime Issues:** Check platform notes below and ensure necessary build tools/libraries are installed.
- **Invalid JSON (`--target-env`):** Ensure proper quoting, especially when used in a shell.
- **Unsupported Placeholder (`env:`) in Some Clients (Cursor, Windsurf, Claude Desktop):** These environments don't pass shell environment variables to `mcp-safe-run`, so `env:` placeholders won't resolve. `file:` and `keyring:` placeholders still work. For example:
```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...]
```
## Platform Notes
- **macOS:** Requires Xcode Command Line Tools.
- **Linux:** Requires `libsecret-1-dev` and build tools like `build-essential`.
- **Windows:** Requires Visual Studio Build Tools (can be installed via `npm install --global --production windows-build-tools`).
---
## Setup for IDEs (Cursor, Windsurf, Claude Desktop)
To use this project with an IDE that supports Model Context Protocol (like Cursor, Windsurf, or Claude Desktop), add an `mcpServers` section to your settings (such as `mcp_settings.json`). This enables the IDE to launch the MCP server with secure environment resolution.
**Example configuration:**
```json
{
"mcpServers": {
"github": {
"command": "mcp-safe-run",
"args": [
"--target-env",
"{\"GITHUB_TOKEN\": \"keyring:mcp-github:personal-pat\"}",
"--",
"npx",
"-y",
"@modelcontextprotocol/server-github"
],
"env": {}
}
}
}
```
### Setting Up Secrets for IDE Integration
#### Option 1: Using a Key File (`file:`)
1. Create a hidden directory for your secrets (if it doesn't exist):
```sh
mkdir -p ./secrets
```
2. Add a `.gitignore` rule to keep secrets out of version control:
```
# .gitignore
/secrets/*
```
3. Create your secret file, e.g. `./secrets/github_token.txt`, and paste your token or secret value inside.
4. Secure the file so only your user can read it:
```sh
chmod 600 ./secrets/github_token.txt
```
5. In your configuration, use a `file:` placeholder, e.g.:
```json
{ "GITHUB_TOKEN": "file:./secrets/github_token.txt" }
```
#### Option 2: Using the OS Keychain (`keyring:`) on macOS
1. Open the **Keychain Access** app (Applications > Utilities > Keychain Access).
2. Click the `+` button to add a new password item.
3. Set the **Keychain Item Name** (service) and **Account Name** (account) to match your placeholder, for example:
- Service: `mcp-github`
- Account: `personal-pat`
4. Paste your secret/token into the "Password" field and save.
5. Alternatively, you can use the `keytar` Node.js CLI or API to add secrets programmatically:
```js
// Example using keytar in Node.js
const keytar = require('keytar');
keytar.setPassword('mcp-github', 'personal-pat', 'ghp_...your_token...');
```
6. In your configuration, use a `keyring:` placeholder, e.g.:
```json
{ "GITHUB_TOKEN": "keyring:mcp-github:personal-pat" }
```
### Notes:
- The `GITHUB_TOKEN` will be securely resolved from your OS keychain using the `keyring:` placeholder.
- You may need to add the secret to your keychain using a tool like `keytar` or your OS's secret manager.
- This pattern works for any MCP server; just adjust the command and arguments as needed for your use case.
- In these IDEs, `env:` placeholders are generally not supported (the IDE does not pass your shell environment), so prefer `keyring:` or `file:` placeholders.
---
