@sealgate/bash-mcp

@sealgate/bash-mcp

A thin stdio MCP server that exposes full bash command execution as a single run tool. The SealGate daemon spawns it on the user's machine and talks to it over stdio; because it runs arbitrary shell, every call is mediated by the SealGate data firewall (the run tool is classified SECRET).

It is the raw-shell sibling of servers/adb: where adb wraps the Android Debug Bridge, this wraps /bin/bash -c <command>.

Usage

# Expose bash over stdio MCP:
npx -y @sealgate/bash-mcp

# Pin a default working directory at launch:
npx -y @sealgate/bash-mcp --cwd /path/to/project

The server speaks MCP over stdio and exposes one tool:

run

Run a single bash command and return its result.

Field	Type	Required	Description
command	string	yes	The bash command line, e.g. ls -la | head. Full shell syntax.
cwd	string	no	Absolute path to the working directory. Blank counts as omitted.
stdin	string	no	Data piped to the command on stdin, followed by EOF.
timeout_ms	number	no	Per-call timeout in milliseconds. Overrides the server default.

The result is a single text block reporting the exit code (or the signal that killed it), then the non-empty stdout and stderr sections. isError is set on a non-zero exit, a timeout, a killing signal, or a shell launch failure. Output is bounded per stream (5 MiB, truncated with a marker). While a command runs the server emits MCP notifications/progress (per output line + a periodic heartbeat) when the caller supplies a progressToken.

Environment

Variable	Default	Description
BASH_MCP_TIMEOUT_MS	120000	Per-run subprocess timeout in ms (a per-call timeout_ms wins).
BASH_MCP_HEARTBEAT_MS	10000	Interval between progress heartbeats while a command is live.
BASH_MCP_SHELL	/bin/bash	Shell used to interpret the command string.
BASH_MCP_CWD	(unset)	Server-wide default working directory; --cwd or a per-call arg wins.
BASH_MCP_ALLOW	(unset)	Optional comma-separated allowlist of program names (see below).

Security notes

• This server runs arbitrary shell commands. It is meant to run behind the SealGate firewall, which classifies run SECRET and mediates every call.
• run acts on the user's own machine, so per the catalog contract it is write_operation: false (not the trifecta's external-write leg) and gated by acl: SECRET, matching servers/adb's execute_adb_command.
• BASH_MCP_ALLOW is a coarse defence-in-depth knob: when set, the first bare word of the command (by basename) must be in the list. It does not parse the full command line (it will not catch sh -c "..." or a $(...) substitution) and is not a substitute for the firewall. Unset means "allow anything", the default for full-bash exposure.
• Output is bounded per stream (5 MiB) and truncated with a marker, so a runaway command cannot exhaust memory.

Development

bun install
bun run build       # tsc -> dist/
bun run typecheck
bun run test        # vitest