MCP Shell Server
Securely execute whitelisted shell commands over MCP, with stdin, argv pipelines, timeouts, and audit logging.
Add to your client
Copy the config for your MCP client and paste it into its config file.
pip install mcp-shell-serverPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"mcp-shell-server": {
"command": "uvx",
"args": [
"mcp-shell-server"
],
"env": {
"ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
}
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.11 or higher
- mcp>=1.1.0
- uv / uvx (or pip) to install and run the server
- An ALLOW_COMMANDS (or ALLOWED_COMMANDS) value listing the command names you want to permit
About MCP Shell Server
A secure MCP server for executing whitelisted shell commands. The model sends a command as an array of argv elements (optionally with stdin, a working directory, and a timeout); the server validates it against an allowlist, hardens arguments against known exec-capable vectors, runs it via subprocess argv (no shell string), and returns stdout, stderr, exit status, and execution time. Designed around defense-in-depth: command whitelisting, argv-only execution, contained redirection, environment isolation, execution limits, and redacted structured audit logging.
Tools & capabilities (1)
shell command executionExecutes a whitelisted shell command. Arguments: command (string[], required) — the command and its arguments as array elements; stdin (string, optional) — input passed to the command; directory (string, optional) — working directory, defaulting to and resolving relative paths from the server process CWD; timeout (integer, optional) — maximum execution time in seconds, clamped to the server maximum. Returns stdout, stderr, status (exit code), and execution_time; on failure also returns an error field.
When to use it
- Let an AI assistant run a tightly scoped set of read-only inspection commands (ls, cat, pwd, grep, wc, find) on a host
- Pass data to a command via stdin and capture its stdout/stderr and exit status
- Run safe argv-based pipelines without exposing a full shell to the model
- Provide command execution with enforced timeouts and output caps so a runaway command cannot hang or flood the agent
- Audit every command an agent runs through structured, secret-redacted log events
Security notes
Only command names listed in ALLOW_COMMANDS / ALLOWED_COMMANDS (or matched by full-match ALLOW_PATTERNS) can run. Commands execute via argv without a shell, so no shell-string injection. Default argument hardening rejects known exec-capable vectors (shells/interpreters, env, xargs, find -exec, awk system(), tar --checkpoint-action=exec, git external aliases) even for allowlisted binaries. Redirection paths must be relative to the working directory; absolute paths, .. traversal, and symlink escapes are rejected. Child processes get a minimal environment (PATH plus Windows launch keys); parent secrets are not inherited unless explicitly named in MCP_SHELL_CHILD_ENV_ALLOWLIST. Execution limits: default timeout 30s, max timeout 300s, output cap 1 MiB per stream. Each invocation emits a redacted structured audit log (secret-like argv/env values are redacted; stdout/stderr bodies are not logged). This is not an OS sandbox: allowed binaries can still read accessible files or consume CPU, so run hostile workloads inside an external container/VM/OS policy boundary.
MCP Shell Server FAQ
How do I control which commands the server can run?
Set the ALLOW_COMMANDS (or its alias ALLOWED_COMMANDS) environment variable to a comma-separated list of command names, e.g. ALLOW_COMMANDS="ls,cat,echo". Only those names are permitted. You can also use ALLOW_PATTERNS for comma-separated regex patterns matched against command names with full-match semantics.
Does allowlisting a command make it safe?
Allowlisting reduces accidental exposure but is not an OS sandbox. The server applies default argument hardening (rejecting find -exec, shells/interpreters, env, xargs, awk system(), tar --checkpoint-action=exec, git external aliases), but allowed binaries can still read accessible files or consume CPU. For hostile workloads, run the server inside a container, VM, or OS policy boundary.
Are my environment secrets exposed to executed commands?
No. Child processes receive only a minimal environment (PATH plus Windows launch keys), so parent secrets like API tokens are not inherited by default. To forward specific variables, list their exact names in MCP_SHELL_CHILD_ENV_ALLOWLIST.
What are the execution limits?
MCP_SHELL_DEFAULT_TIMEOUT_SECONDS defaults to 30 seconds, MCP_SHELL_MAX_TIMEOUT_SECONDS to 300 seconds, and MCP_SHELL_OUTPUT_LIMIT_BYTES to 1 MiB per captured stdout/stderr stream. Client timeouts are clamped to the server maximum; processes that time out or exceed the output cap are terminated.
Can I install it automatically for Claude Desktop?
Yes. Via Smithery: npx -y @smithery/cli install mcp-shell-server --client claude. For manual installation, use pip install mcp-shell-server, or run it directly with uvx mcp-shell-server.
Alternatives to MCP Shell Server
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
LSP-powered coding agent toolkit: semantic symbol search, references and structural edits.
Compare MCP Shell Server with: