shell

Run shell commands restricted to a strict basename allowlist. No shell expansion: arguments are passed directly to exec(), never through /bin/sh. There is no glob, pipe, redirect, or variable substitution.

Usage

native-mcp shell --allow CMD,CMD,... [--cwd DIR] [--timeout DUR]

--allow is required: the server refuses to start without it. There is no "open mode".

Flags

Flag	Default	Description
--allow	(required)	Comma-separated list of allowed command basenames (e.g. ls,grep,find,git,cat).
--cwd	(none)	If set, all commands run in this directory. The tool's cwd argument is then rejected.
--timeout	30s	Per-command timeout (Go duration).

Tools

run

Field	Type	Required	Description
command	string	yes	Basename of the command (must be in --allow). Paths are rejected.
args	array<string>	no	Argument list, passed verbatim to exec().
stdin	string	no	Optional stdin content.
cwd	string	no	Working directory. Rejected if --cwd was set on the server.

Returns:

exit: 0
cwd: /tmp                    (only if a cwd was used)
---- stdout ----
<command stdout, capped at 1 MiB>
---- stderr ----
<command stderr, capped at 1 MiB>

list_allowed_commands

Returns the configured allowlist, one per line.

Why this design

• No /bin/sh — every byte of args reaches the binary unchanged. Quoting is a non-issue.
• Basename-only command — paths like /bin/sh or ../bin/sh are rejected. The actual binary is resolved via PATH server-side.
• Allowlist required — there is no "yolo mode" that exposes every command on disk.
• Output capped — runaway commands cannot blow up the agent's context.
• Timeout — runaway commands cannot hang the session.

Register in Claude Code

# Read-only tools for code exploration
claude mcp add native-shell native-mcp shell --allow ls,find,grep,cat,head,tail,wc

# Locked to one project, with longer timeout for builds
claude mcp add native-shell-build native-mcp shell \
  --allow make,cargo,go,npm \
  --cwd /home/you/project \
  --timeout 5m