MCP Directory

How to add wcgw to Windsurf

Shell and coding agent for Claude and other MCP clients with tightly integrated shell and file-editing tools. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf config for wcgw

uvx --python 3.12 wcgw@latest
{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "wcgw@latest"
      ]
    }
  }
}

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

Before you start

  • uv (install via Homebrew on Mac/Linux: brew install uv)
  • Python 3.12 (managed automatically by uvx)
  • On Windows, only works under WSL
  • Optional: screen, for attaching to the agent's working terminal
  • Optional: the wcgw VS Code extension (AmanRusia.wcgw)

What wcgw can do in Windsurf

Initialize

Reset shell and set up workspace environment. Parameters: any_workspace_path, initial_files_to_read, mode_name ('wcgw'|'architect'|'code_writer'), task_id_to_resume.

BashCommand

Execute shell commands with timeout control, or send interactive input (text, special keys like Enter/Key-up, or ASCII codes) to a running command. Parameters include command, send_text, send_specials, send_ascii, wait_for_seconds.

ReadFiles

Read content from one or more files. Parameters: file_paths (string[]).

WriteIfEmpty

Create new files or write to empty files. Parameters: file_path, file_content.

FileEdit

Edit existing files using search/replace blocks. Parameters: file_path, file_edit_using_search_replace_blocks.

ReadImage

Read image files for display/processing. Parameters: file_path.

ContextSave

Save project context and files for knowledge transfer or saving task checkpoints to be resumed later. Parameters: id, project_root_path, description, relevant_file_globs.

Security

This MCP server provides unfiltered access to your machine's shell and files. It does NOT restrict the LLM from executing arbitrary commands or making unintended changes, and can be misused by attackers or run dangerous commands if the AI hallucinates. Run only if you fully understand and accept the risks of running AI agents with no restrictions. 'architect' and 'code-writer' modes offer some restriction, but in code-writer mode the allowed-commands list is only an instruction to Claude and is not actually enforced (WIP).

wcgw + Windsurf FAQ

Where is the Windsurf config file?

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

Is wcgw safe to use with Windsurf?

This MCP server provides unfiltered access to your machine's shell and files. It does NOT restrict the LLM from executing arbitrary commands or making unintended changes, and can be misused by attackers or run dangerous commands if the AI hallucinates. Run only if you fully understand and accept the risks of running AI agents with no restrictions. 'architect' and 'code-writer' modes offer some restriction, but in code-writer mode the allowed-commands list is only an instruction to Claude and is not actually enforced (WIP).

Does this restrict what the AI can do on my machine?

No. By default (wcgw mode) it provides unfiltered access to your shell and files with no restrictions. 'architect' mode is read-only and 'code-writer' mode limits editable paths, but in code-writer mode the allowed-commands list is only an instruction to Claude and is not actually enforced. Run only if you accept the risks.

Does it work on Windows?

Only under WSL. Configure claude_desktop_config.json to launch via wsl.exe with the uvx/uv command.

How do I attach to the terminal the AI is using?

If 'screen' is installed, wcgw runs on a screen instance automatically. List sessions with 'screen -ls', then attach with 'screen -x <session>'. Detach with Ctrl+a+d (not exit). The wcgw VS Code extension can also attach automatically when the workspace path matches.

View repo Full wcgw page