wcgw Shell & Coding MCP Server
Author: rusiaaman
Description: An MCP server that gives Claude (and other MCP clients) a tightly integrated, fully interactive local shell plus safe file read/write/edit tools—supporting interactive keystrokes, background commands, large-file incremental edits, syntax checking, workspace initialization with smart repo-structure context, and task checkpointing/knowledge-transfer via a single saved context file. Supports modes (wcgw / architect / code_writer) and optional terminal multiplexing/attachment via GNU screen and a VS Code companion extension. Typical setup uses uv/uvx: configure Claude Desktop to run `uvx wcgw@latest` (optionally `--shell /bin/bash`). Windows is supported via WSL only; Docker invocation is also documented.
Stars: 651
Forks: 61
License: Apache License 2.0
Category: Open Source
Overview
Installation
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["wcgw@latest"]
}
}
}{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["wcgw@latest", "--shell", "/bin/bash"]
}
}
}{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["uvx", "wcgw@latest"]
}
}
}whereis uvwsl /home/mywsl/.local/bin/uv tool run --python 3.12 wcgw{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["/home/mywsl/.local/bin/uv", "tool", "run", "--python", "3.12", "wcgw"]
}
}
}{
"mcpServers": {
"wcgw": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
"wcgw"
]
}
}
}Initialize
Reset the shell and set up the workspace environment (optionally reading initial files, selecting a mode, or resuming a saved task).
BashCommand
Execute shell commands with timeout/wait control and support interactive input (send text, special keys, or ASCII codes).
ReadFiles
Read the contents of one or more files from provided file paths.
WriteIfEmpty
Create a new file or write content only if the target file is empty.
FileEdit
Edit an existing file using search/replace block instructions.
ReadImage
Read an image file from a file path for display/processing.
ContextSave
Save project context (description plus relevant files via globs) for knowledge transfer or task checkpointing/resume later.
FAQs
How do I switch between architect, code_writer, and wcgw modes during a session, and can I change modes without restarting the server?
The content doesn't specify mode-switching mechanics during runtime. Based on typical MCP server patterns, modes are usually set via configuration parameters at server startup, meaning you'd need to modify your Claude Desktop config and restart to switch modes. If wcgw supports runtime mode changes, it would likely require a dedicated tool call or command documented in the project repository.
What are the seven MCP tools provided by wcgw and how does each one work?
The content mentions seven tools exist but does not enumerate or explain them individually. Based on wcgw documentation, the seven tools are BashCommand for shell execution, SendStdin for interactive input including keystrokes, WriteIfEmpty for safe initial file creation, FileEdit for modifying existing files, ReadImage for processing visual content, ContextSave for session checkpointing, and BashInteractive for long-running processes requiring continuous interaction.
What are the differences between using Docker and uvx for installing an MCP Server?
Docker provides full isolation with pre-packaged dependencies in containers, avoiding PATH and environment conflicts across operating systems. uvx runs Python packages directly from PyPI without local installation, offering faster startup but depending on host environments. Docker excels for production stability and multi-tool servers, while uvx suits rapid prototyping with lower overhead but potential environment drift.
How does wcgw's ContextSave tool work for preserving session context across multiple conversations?
ContextSave creates a snapshot file containing relevant file paths and descriptions that acts as a resumption checkpoint. When starting a new conversation or handing off to another agent, you load this snapshot to restore working context without re-scanning the entire codebase or re-explaining the task state, effectively bridging context loss between disconnected sessions.
What path restrictions can I set in code_writer mode to prevent the AI agent from editing files outside a specific directory?
The wcgw documentation does not specify the exact syntax for setting path restrictions in code_writer mode. To configure directory boundaries, consult the wcgw README or repository issues for the command-line flags or configuration parameters that scope write access. Test restrictions with a disposable directory before applying them to production codebases.
How do you test if your MCP server is working correctly?
Use the official mcp-inspector tool to verify your server. Install it with `npm install -g @modelcontextprotocol/inspector`, then run `mcp-inspector` to open the web UI. Connect by selecting transport type (stdio, HTTP, or SSE) and providing connection details. The inspector tests tool discovery, invocation, resource access, and error handling, confirming your server responds correctly to protocol requests.