Vaultshell MCP server

vaultshell

English | 简体中文

Available on the official MCP Registry: io.github.SoWhatI/vaultshell

An MCP server that stores secrets in local secure storage, injects them into shell child processes at exec time based on rules, and guarantees secret plaintext never reaches the model context — not in tool responses, not in logs, not in audit records.

The closed loop: reference-based storage + conditional injection + mandatory output redaction.

Status: M3 — one-shot commands + persistent sessions + credential proxy +

external CLI backends. See

CHANGELOG and docs/design-spec.md.

The iron rule

masks ([REDACTED:NAME]), and redacted output.

• No MCP tool returns secret plaintext — ever. Responses contain only names,

child process env and never pass through the tool layer.

• Resolvers are only invoked inside the launcher; values go straight into the

reference only.

• shellexec has no** free-form env parameter. Secrets enter by rule

• Redactor failures are fail-closed: output is discarded, never returned raw.

Quick start

Requires Node.js 20+.

Install from GitHub (no npm registry account needed)

# Run on demand directly from the repo (npm installs devDependencies and
# builds dist/ via the `prepare` script):
npx -y github:SoWhatI/vaultshell

# Or install globally:
npm i -g github:SoWhatI/vaultshell

This is the same code as the npm registry package, installed from git — npm clones the repo, runs prepare (→ npm run build) and links the vaultshell bin. Pin a tag for reproducibility: npx -y github:SoWhatI/vaultshell#v0.1.1.

Docker (ghcr.io)

docker run -i --rm \
  -e MASTER_KEY=<64 hex chars> \
  -v ~/.vaultshell:/home/node/.vaultshell \
  ghcr.io/sowhati/vaultshell:latest

MCP client config using Docker:

{
  "mcpServers": {
    "vaultshell": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MASTER_KEY=<64 hex chars>",
        "-v", "~/.vaultshell:/home/node/.vaultshell",
        "ghcr.io/sowhati/vaultshell:latest"
      ]
    }
  }
}

The image runs as the non-root node user (HOME=/home/node), so the data volume mounts at /home/node/.vaultshell. node-pty is excluded from the image — sessions automatically fall back to pipe mode (pty: false) in containers; injection and redaction are unchanged. The web subcommand passes through (docker run … ghcr.io/sowhati/vaultshell web — loopback inside the container, of limited use).

No Smithery distribution: Smithery has gone hosted-only (it only

accepts servers deployed to its own infrastructure). vaultshell's secrets

must stay on the user's machine by design — third-party hosting is

incompatible with its threat model, so we deliberately do not publish

there.

From source

# Run via npx (after publish) or from source:
npm install && npm run build

# 1. Create a master key for the encrypted-file backend
export MASTER_KEY=$(openssl rand -hex 32)

# 2. Create ~/.vaultshell/config.yaml and ~/.vaultshell/rules.yaml
#    (full annotated examples: docs/user-guide.md)

# 3. Store a secret (never echoed back) and run with injection
#    via your MCP client's tools: secret_set, then shell_exec

Claude Desktop (claudedesktopconfig.json):

{
  "mcpServers": {
    "vaultshell": {
      "command": "npx",
      "args": ["-y", "vaultshell"],
      "env": { "MASTER_KEY": "<64 hex chars>" }
    }
  }
}

Full setup, configuration reference, rule-writing guide, client integration, and FAQ: docs/user-guide.md.

MCP tools

Shortened. The full README is on GitHub.