MCP Directory

How to add MCP Shell Server to Claude Desktop

Securely execute whitelisted shell commands over MCP, with stdin, argv pipelines, timeouts, and audit logging. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 176★ · stdio · no auth

Claude Desktop config for MCP Shell Server

pip install mcp-shell-server
{
  "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.

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the MCP Shell Server config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm MCP Shell Server's tools appear under the 🔌 tools menu.

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

What MCP Shell Server can do in Claude Desktop

shell command execution

Executes 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.

Security

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the MCP Shell Server config there under the "mcpServers" key and restart the client.

Is MCP Shell Server safe to use with Claude Desktop?

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.

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.

View repo Full MCP Shell Server page