MCP Directory

How to add MCP Shell Server to Windsurf

Securely execute whitelisted shell commands over MCP, with stdin, argv pipelines, timeouts, and audit logging. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the MCP Shell Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5MCP Shell Server's tools become available to Cascade.

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 Windsurf

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_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 Windsurf?

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