MCP Directory

How to add CLI MCP Server to Windsurf

Securely run whitelisted CLI commands within an allowed directory via MCP. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf config for CLI MCP Server

npx @smithery/cli install cli-mcp-server --client claude
{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

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 CLI MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5CLI MCP Server's tools become available to Cascade.

Before you start

  • Python 3.10+
  • MCP protocol library
  • uv / uvx (for running the server)

What CLI MCP Server can do in Windsurf

run_command

Executes whitelisted CLI commands within allowed directories. Takes a single command string (e.g., 'ls -l' or 'cat file.txt'). Shell operators are not supported unless ALLOW_SHELL_OPERATORS=true; commands and flags must be whitelisted unless set to 'all'; all paths are validated to be within ALLOWED_DIR.

show_security_rules

Displays the current security configuration and restrictions, including the working directory, allowed commands, allowed flags, and security limits (max command length and timeout).

Security

Shell operators (&&, |, >, >>) are blocked by default but can be enabled with ALLOW_SHELL_OPERATORS=true. Commands must be whitelisted unless ALLOWED_COMMANDS='all'; flags must be whitelisted unless ALLOWED_FLAGS='all'. Setting either to 'all' removes that restriction entirely. All paths are validated and normalized to be within ALLOWED_DIR, with path-traversal prevention and symlink resolution. Execution is bounded by MAX_COMMAND_LENGTH and COMMAND_TIMEOUT.

CLI MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the CLI MCP Server config there under the "mcpServers" key and restart the client.

Is CLI MCP Server safe to use with Windsurf?

Shell operators (&&, |, >, >>) are blocked by default but can be enabled with ALLOW_SHELL_OPERATORS=true. Commands must be whitelisted unless ALLOWED_COMMANDS='all'; flags must be whitelisted unless ALLOWED_FLAGS='all'. Setting either to 'all' removes that restriction entirely. All paths are validated and normalized to be within ALLOWED_DIR, with path-traversal prevention and symlink resolution. Execution is bounded by MAX_COMMAND_LENGTH and COMMAND_TIMEOUT.

How do I allow any command or flag?

Set ALLOWED_COMMANDS or ALLOWED_FLAGS to 'all'. This removes the respective whitelist restriction; otherwise only the comma-separated listed values are permitted.

Why are shell operators like && and | not working?

Shell operators (&&, ||, |, >, >>) are blocked by default to prevent injection. Enable them by setting ALLOW_SHELL_OPERATORS=true.

What configuration is required?

ALLOWED_DIR is required and has no default; it sets the base directory for command execution. All other variables (ALLOWED_COMMANDS, ALLOWED_FLAGS, MAX_COMMAND_LENGTH, COMMAND_TIMEOUT, ALLOW_SHELL_OPERATORS) have defaults.

View repo Full CLI MCP Server page