WCWG

You can run the wcgw MCP server on your device to give a fully interactive shell and coding environment to your chat application clients. It enables you and the agent to code, build, and run on your local machine with an integrated editor experience and multiplex terminal support for productive interactions.

How to use

To use wcgw with an MCP client, connect to one of the available MCP server configurations and start an interactive session. You can instruct the agent to execute shell commands, read files, edit files, and run your code. The agent can operate in an attached terminal, share the workspace, and preserve context for task checkpoints or knowledge transfer. You can switch between modes to plan, edit, or run code as needed. If you want to explore a project interactively, attach to the working terminal and issue commands through your MCP client, while the agent guides you through changes and verifications.

How to install

Prerequisites vary by your environment. The wcgw setup relies on the uv tool for managing the MCP runtime, and you can run the server via different host commands described below.

Install on macOS and Linux (via uvx)

Install uv using Homebrew, then configure Claude to use the wcgw MCP server.

Install uv (required):

Step-by-step configuration for Claude (macOS and Linux)

1. Install uv with Homebrew

2. Create or update claude_desktop_config.json with the wcgw MCP server configuration using uvx

3. Restart Claude to apply the new MCP server configuration

Optional: Force a specific shell by adding a --shell setting in the configuration to point to /bin/bash or another shell path, if you prefer a non-default shell.

Example configuration for Claude (macOS/Linux)

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

Optional: Specify a shell

To force a specific shell, add the --shell flag to the wcgw configuration.

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

Troubleshooting configuration issues

If you encounter an uv ENOENT error, ensure uv is installed and accessible from your PATH. Verify uv with which uv and adjust the configuration accordingly. If problems persist, run the following test command to verify the runtime:

uv tool run --python 3.12 wcgw

Windows on WSL setup

On Windows using WSL, configure Claude to connect through wsl.exe and uvx for the wcgw server.

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

Usage with Docker

You can run wcgw via Docker. Use the following MCP configuration to start wcgw inside a container. This example binds a host workspace directory into the container and runs wcgw. Adjust paths as needed.

{
  "mcpServers": {
    "wcgw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
        "wcgw"
      ]
    }
  }
}

Attach to the working terminal

If the editor or terminal extension supports multiplexed terminals, you can attach to the terminal that the AI uses for running commands. You can attach from the terminal view or use the screen session if you have a screen-based workflow. This allows you to monitor and interact with long-running tasks without losing context.

Available tools

Initialize

Reset the shell and set up the workspace environment for a clean session.

BashCommand

Execute shell commands with timeout control and the ability to send text or keystrokes to the running command.

ReadFiles

Read content from one or more files to inform edits or decisions.

WriteIfEmpty

Create new files or write to files that are currently empty.

FileEdit

Edit existing files using search/replace blocks with context-aware matching and tolerance for formatting.

ReadImage

Read image files for display or processing within the workflow.

ContextSave

Save project context and files for knowledge transfer or to resume tasks later.