Server facts
wcgw MCP Server
Project
- Author
- rusiaaman
- Repository
- github.com/rusiaaman/wcgw
- License
- Apache-2.0
- Category
- Developer Tools
Tech
- Runtime / language
- pythonPython
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 678
- Last commit
- Data as of
Tags
- Claude
- Code Editing
- Python
- Shell
- Terminal
Overview
wcgw combines an interactive shell with code-reading and editing operations for MCP clients. It is designed for workflows where a conversational assistant runs commands, changes files, and checks results on the user's machine. Unlike a simple command runner, its shell supports interactive input, special keys, background commands, and shared terminal access. A VS Code extension can attach to that terminal, while screen provides another documented way for a person to watch or interact with the same session. Bash and zsh are supported shell choices.
File operations include incremental search-and-replace editing, large-file chunking, and syntax feedback after changes. A file must be read before the assistant can modify it. Initialization returns selected workspace structure and can load project or global instruction files. ContextSave preserves task information for continuation in another chat. Three modes organize usage: architect for investigation, code-writer for path-scoped edits, and the default unrestricted wcgw mode. These features do not turn the tool into a security sandbox. The README warns that shell and filesystem access can execute arbitrary commands, and says command allow-lists in code-writer mode are instructions rather than enforced checks. Installation uses uvx with Python 3.12; Windows operation requires WSL. It suits users who understand and accept the risks of a locally empowered coding agent.
Install & configure
Requirements
- uv / uvx available to the MCP client
- Python 3.12 for the documented launch
- WSL on Windows
uvx --python 3.12 wcgw@latestThe README documents this configuration for Claude Desktop. A --shell argument can select bash or zsh. Understand the unrestricted shell and file-access risks before running it.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": [
"--python",
"3.12",
"wcgw@latest"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": [
"--python",
"3.12",
"wcgw@latest"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"wcgw": {
"type": "stdio",
"command": "uvx",
"args": [
"--python",
"3.12",
"wcgw@latest"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": [
"--python",
"3.12",
"wcgw@latest"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"wcgw": {
"type": "stdio",
"command": "uvx",
"args": [
"--python",
"3.12",
"wcgw@latest"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| Initialize | Set up the shell and workspace, or resume saved task context. |
| BashCommand | Run shell commands or send interactive input to the terminal. |
| ReadFiles | Read one or more files into the assistant context. |
| WriteIfEmpty | Write a new file or populate an empty one. |
| FileEdit | Modify a file using search-and-replace blocks. |
| ReadImage | Load an image file for inspection. |
| ContextSave | Store task context and relevant files for later continuation. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Run compiler checks and iterate on code changes.
- Share an interactive terminal with an assistant.
- Edit large files through incremental replacements.
- Save a task checkpoint and resume it in another chat.
Strengths
- Interactive terminal supports keys and concurrent background commands.
- File edits provide syntax feedback and require a prior read.
- Context checkpoints support work across chats.
Limitations
- Default mode gives unrestricted shell and filesystem access.
- Code-writer command lists are not enforced allow-lists.
- Windows requires WSL.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
