MCP Directory

How to add MCP Shell Server to Cursor

Securely execute whitelisted shell commands over MCP, with stdin, argv pipelines, timeouts, and audit logging. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the MCP Shell Server config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of MCP Shell Server's tools to confirm it's connected.

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 Cursor

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

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the MCP Shell Server config there under the "mcpServers" key and restart the client.

Is MCP Shell Server safe to use with Cursor?

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