wcgw

wcgw is an MCP server that provides an interactive shell and code editing capabilities integrated with Claude and other MCP clients. It enables a fully interactive terminal experience, including sending keystrokes and managing background commands, with a multiplexed terminal that can be attached from VS Code via the wcgw extension. This means you can run and edit code, execute commands, and iterate with real-time feedback in a collaborative agent-enabled workflow. The server ships with modes to tailor behavior for planning (architect), code editing (code-writer), or unrestricted work (wcgw). When using Claude’s MCP client, you can attach to the same terminal the AI uses, view command history, and load project files (CLAUDE.md/AGENTS.md) automatically during initialization to guide instructions and tasks.

Prerequisites:

• A supported environment (macOS, Linux, or Windows with WSL).
• uv (the Universal Viewer/CLI tool) installed and available in your PATH. Install via Homebrew on macOS/Linux: brew install uv, or follow uv’s installation guide for your OS.

Install and configure the MCP server:

1. Install uvx via your package manager or as described in the UV docs. This will fetch and install the wcgw MCP server image when run with wcgw@latest.
2. Create or update Claude’s MCP configuration to point to the wcgw server:

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

3. Restart Claude (or your MCP client) to pick up the new configuration.
4. Optional: To force a specific shell for the wcgw process, add the --shell argument:

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": ["wcgw@latest", "--shell", "/bin/bash"]
    }
  }
}

5. If you encounter issues such as uv not found (ENOENT), ensure uv is installed and accessible in your PATH, or point to the full path of uv as shown in your environment. You can test the server locally by running:

uv tool run --python 3.12 wcgw

6. On Windows (WSL), configure Claude to use wsl.exe with uvx and wcgw@latest as described in the README, then test using the provided uv invocation inside WSL.

Tips and common issues:

• Ensure uv is installed and accessible in your environment; if you get an error, verify with which uv (or whereis uv on Linux).
• If you need a consistent shell, you can pass a specific shell path via --shell in the uvx arguments.
• The wcgw server supports interactive commands and background processes; use the multiplex terminal to attach and manage processes in parallel.
• When troubleshooting, run the suggested uv tool commands in your terminal to verify that the server can start and that Python 3.12 is supported.
• Claude will automatically load CLAUDE.md or AGENTS.md from your project root (and additional global configs) during initialization to guide interactions.