mcp-wcgw
wcgw is an MCP server providing unrestricted shell and file operations for coding agents, with interactive terminal control, file editing protections, and project context management.
Run shell commands with timeout, status checks, background execution, and interactive input (keys, ASCII, special keys)
Initialize/reset shell workspace in modes: wcgw, architect, and code_writer (with allowed commands/globs)
Read files with optional line ranges and read images
Write or edit files via full rewrite or search/replace blocks, with syntax checking and protections
Save project context/knowledge transfer (ContextSave) and resume tasks
Attach to the AI's terminal via screen/VSCode extension
Auto-load CLAUDE.md/AGENTS.md instructions
Supports running the MCP server over Docker with volume mounting capabilities
Enables interaction with GitHub through the GitHub CLI to create PRs and work with repositories
Allows custom GPT models to communicate with the user's shell via a relay server
Can be used in conjunction with puppeteer MCP for browser automation tasks
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-wcgw check syntax and lint the current Python project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shell and Coding agent for Claude and other mcp clients
Empowering chat applications to code, build and run on your local machine.
wcgw is an MCP server with tightly integrated shell and code editing tools.
⚠️ Warning: This MCP server provides unfiltered access to your machine's shell and files. It does not restrict LLMs from executing arbitrary commands or making unintended changes. This tool can be misused by attackers or run dangerous commands if the AI hallucinates. Run this repository only if you fully understand and accept the risks associated with running AI agents with no restrictions.
As of 2026 the reason you could use wcgw is that it provides fully interactive shell experience that you and the agent both can control (including sending key-strokes).
Combined with the wcgw vscode extension that attaches the agent's shell in your editor, you can get the best agentic shell experience that is out there.
The file editing tricks and the general minimalism also helps agent be more productive.
Demo

Related MCP server: Claude Code Control MCP
Updates
[6 Oct 2025] Model can now run multiple commands in background. ZSH is now a supported shell. Multiplexing improvements.
[27 Apr 2025] Removed support for GPTs over relay server. Only MCP server is supported in version >= 5.
[24 Mar 2025] Improved writing and editing experience for sonnet 3.7, CLAUDE.md gets loaded automatically.
[16 Feb 2025] You can now attach to the working terminal that the AI uses. See the "attach-to-terminal" section below.
[15 Jan 2025] Modes introduced: architect, code-writer, and all powerful wcgw mode.
[8 Jan 2025] Context saving tool for saving relevant file paths along with a description in a single file. Can be used as a task checkpoint or for knowledge transfer.
[29 Dec 2024] Syntax checking on file writing and edits is now stable. Made
initializetool call useful; sending smart repo structure to claude if any repo is referenced. Large file handling is also now improved.[9 Dec 2024] Vscode extension to paste context on Claude app
🚀 Highlights
⚡ Create, Execute, Iterate: Ask claude to keep running compiler checks till all errors are fixed, or ask it to keep checking for the status of a long running command till it's done.
⚡ Large file edit: Supports large file incremental edits to avoid token limit issues. Smartly selects when to do small edits or large rewrite based on % of change needed.
⚡ Syntax checking on edits: Reports feedback to the LLM if its edits have any syntax errors, so that it can redo it.
⚡ Interactive Command Handling: Supports interactive commands using arrow keys, interrupt, and ansi escape sequences.
⚡ File protections:
The AI needs to read a file at least once before it's allowed to edit or rewrite it. This avoids accidental overwrites.
Avoids context filling up while reading very large files. Files get chunked based on token length.
On initialisation the provided workspace's directory structure is returned after selecting important files (based on .gitignore as well as a statistical approach)
File edit based on search-replace tries to find correct search block if it has multiple matches based on previous search blocks. Fails otherwise (for correctness).
File edit has spacing tolerant matching, with warning on issues like indentation mismatch. If there's no match, the closest match is returned to the AI to fix its mistakes.
Using Aider-like search and replace, which has better performance than tool call based search and replace.
⚡ Shell optimizations:
Current working directory is always returned after any shell command to prevent AI from getting lost.
Command polling exits after a quick timeout to avoid slow feedback. However, status checking has wait tolerance based on fresh output streaming from a command. Both of these approach combined provides a good shell interaction experience.
Supports multiple concurrent background commands alongside the main interactive shell.
⚡ Saving repo context in a single file: Task checkpointing using "ContextSave" tool saves detailed context in a single file. Tasks can later be resumed in a new chat asking "Resume
task id". The saved file can be used to do other kinds of knowledge transfer, such as taking help from another AI.⚡ Easily switch between various modes:
Ask it to run in 'architect' mode for planning. Inspired by adier's architect mode, work with Claude to come up with a plan first. Leads to better accuracy and prevents premature file editing.
Ask it to run in 'code-writer' mode for code editing and project building. You can provide specific paths with wild card support to prevent other files getting edited.
By default it runs in 'wcgw' mode that has no restrictions and full authorisation.
More details in Modes section
⚡ Runs in multiplex terminal Use vscode extension or run
screen -xto attach to the terminal that the AI runs commands on. See history or interrupt process or interact with the same terminal that AI uses.⚡ Automatically load CLAUDE.md/AGENTS.md Loads "CLAUDE.md" or "AGENTS.md" file in project root and sends as instructions during initialisation. Instructions in a global "
/.wcgw/CLAUDE.md" or "/.wcgw/AGENTS.md" file are loaded and added along with project specific CLAUDE.md. The file name is case sensitive. CLAUDE.md is attached if it's present otherwise AGENTS.md is attached.
Claude setup (using mcp)
Mac and linux
First install uv using homebrew brew install uv
(Important: use homebrew to install uv. Otherwise make sure uv is present in a global location like /usr/bin/)
Then create or update claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json) with following json.
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["--python", "3.12", "wcgw@latest"]
}
}
}Then restart claude app.
Optional: Force a specific shell
To use a specific shell (bash or zsh), add the --shell argument:
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["--python", "3.12", "wcgw@latest", "--shell", "/bin/bash"]
}
}
}Optional: Streamable HTTP transport
wcgw_mcp keeps stdio as the default transport. For clients or gateways that
work better with a long-lived HTTP MCP endpoint, run:
uvx --python 3.12 wcgw@latest --transport streamable-http --host 127.0.0.1 --port 8765The MCP endpoint is http://127.0.0.1:8765/mcp/. Binding to loopback keeps the
server local while allowing an HTTP-capable local gateway to multiplex requests
without sharing one stdio pipe.
If there's an error in setting up
If there's an error like "uv ENOENT", make sure
uvis installed. Then run 'which uv' in the terminal, and use its output in place of "uv" in the configuration.If there's still an issue, check that
uv tool run --python 3.12 wcgwruns in your terminal. It should have no output and shouldn't exit.Try removing ~/.cache/uv folder
Try using
uvversion0.6.0for which this tool was tested.Debug the mcp server using
npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw
Windows on wsl
This mcp server works only on wsl on windows.
To set it up, install uv
Then add or update the claude config file %APPDATA%\Claude\claude_desktop_config.json with the following
{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["uvx", "--python", "3.12", "wcgw@latest"]
}
}
}When you encounter an error, execute the command wsl uv --python 3.12 wcgw in command prompt. If you get the error /bin/bash: line 1: uv: command not found, it means uv was not installed globally and you need to point to the correct path of uv.
Find where uv is installed:
whereis uvExample output:
uv: /home/mywsl/.local/bin/uv
Test the full path works:
wsl /home/mywsl/.local/bin/uv tool run --python 3.12 wcgwUpdate the config with the full path:
{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["/home/mywsl/.local/bin/uv", "tool", "run", "--python", "3.12", "wcgw"]
}
}
}Replace /home/mywsl/.local/bin/uv with your actual uv path from step 1.
Usage
Wait for a few seconds. You should be able to see this icon if everything goes right.
over here

Then ask claude to execute shell commands, read files, edit files, run your code, etc.
Task checkpoint or knowledge transfer
You can do a task checkpoint or a knowledge transfer by attaching "KnowledgeTransfer" prompt using "Attach from MCP" button.
On running "KnowledgeTransfer" prompt, the "ContextSave" tool will be called saving the task description and all file content together in a single file. An id for the task will be generated.
You can in a new chat say "Resume ''", the AI should then call "Initialize" with the task id and load the context from there.
Or you can directly open the file generated and share it with another AI for help.
Modes
There are three built-in modes. You may ask Claude to run in one of the modes, like "Use 'architect' mode"
Mode | Description | Allows | Denies | Invoke prompt |
Architect | Designed for you to work with Claude to investigate and understand your repo. | Read-only commands | FileEdit and Write tool | Run in mode='architect' |
Code-writer | For code writing and development | Specified path globs for editing or writing, specified commands | FileEdit for paths not matching specified glob, Write for paths not matching specified glob | Run in code writer mode, only 'tests/**' allowed, only uv command allowed |
**wcgw** | Default mode with everything allowed | Everything | Nothing | No prompt, or "Run in wcgw mode" |
Note: in code-writer mode either all commands are allowed or none are allowed for now. If you give a list of allowed commands, Claude is instructed to run only those commands, but no actual check happens. (WIP)
Attach to the working terminal to investigate
NEW: the vscode extension now automatically attach the running terminal if workspace path matches.
If you've screen command installed, wcgw runs on a screen instance automatically. If you've started wcgw mcp server, you can list the screen sessions:
screen -ls
And note down the wcgw screen name which will be something like 93358.wcgw.235521 where the last number is in the hour-minute-second format.
You can then attach to the session using screen -x 93358.wcgw.235521
You may interrupt any running command safely.
You can interact with the terminal safely, for example for entering passwords, or entering some text. (Warning: If you run a new command, any new LLM command will interrupt it.)
You shouldn't exit the session using exit or Ctrl-d, instead you should use ctrl+a+d to safely detach without destroying the screen session.
Include the following in ~/.screenrc for better scrolling experience
defscrollback 10000
termcapinfo xterm* ti@:te@[Optional] Vs code extension
https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw
Commands:
Select a text and press
cmd+'and then enter instructions. This will switch the app to Claude and paste a text containing your instructions, file path, workspace dir, and the selected text.
Examples

Using mcp server over docker
First build the docker image docker build -t wcgw https://github.com/rusiaaman/wcgw.git
Then you can update /Users/username/Library/Application Support/Claude/claude_desktop_config.json to have
{
"mcpServers": {
"wcgw": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
"wcgw"
]
}
}
}Tools
The server provides the following MCP tools:
Shell Operations:
Initialize: Reset shell and set up workspace environmentParameters:
any_workspace_path(string),initial_files_to_read(string[]),mode_name("wcgw"|"architect"|"code_writer"),task_id_to_resume(string),thread_id(string; empty only for the first call)
BashCommand: Execute shell commands with timeout controlParameters:
command(string),wait_for_seconds(int, optional),thread_id(string)Parameters:
send_text(string) orsend_specials(["Enter"|"Key-up"|...]) orsend_ascii(int[]),wait_for_seconds(int, optional)
File Operations:
ReadFiles: Read content from one or more filesParameters:
file_paths(string[]),thread_id(string)
WriteIfEmpty: Create new files or write to empty filesParameters:
file_path(string),file_content(string)
FileEdit: Edit existing files using search/replace blocksParameters:
file_path(string),file_edit_using_search_replace_blocks(string)
ReadImage: Read image files for display/processingParameters:
file_path(string),thread_id(string)
Project Management:
ContextSave: Save project context and files for Knowledge Transfer or saving task checkpoints to be resumed laterParameters:
id(string),project_root_path(string),description(string),relevant_file_globs(string[]),thread_id(string)
All tools support absolute paths and include built-in protections against common errors. See the MCP specification for detailed protocol information.
Available Tools
6 toolsBashCommandADestructive
Execute a bash command. This is stateful (beware with subsequent calls).
Status of the command and the current working directory will always be returned at the end.
The first or the last line might be
(...truncated)if the output is too long.Always run
pwdif you get any file or directory not found error to make sure you're not lost.Do not run bg commands using "&", instead use this tool.
You must not use echo/cat to read/write files, use ReadFiles/FileWriteOrEdit
In order to check status of previous command, use
status_checkwith empty command argument.Only command is allowed to run at a time. You need to wait for any previous command to finish before running a new one.
Programs don't hang easily, so most likely explanation for no output is usually that the program is still running, and you need to check status again.
Do not send Ctrl-c before checking for status till 10 minutes or whatever is appropriate for the program to finish.
Only run long running commands in background. Each background command is run in a new non-reusable shell.
On running a bg command you'll get a bg command id that you should use to get status or interact.
Inputs: type (required), thread_id (required), command, send_text, +6 more.
ContextSaveBRead-only
Saves provided description and file contents of all the relevant file paths or globs in a single text file.
Use the thread_id returned by Initialize when available; legacy clients may omit it.
Provide random 3 word unique id or whatever user provided.
Leave project path as empty string if no project path
Inputs: id (required), description (required), project_root_path (required), relevant_file_globs (required), +1 more.
FileWriteOrEditADestructiveIdempotent
Writes or edits a file based on the percentage of changes.
Use absolute path only (~ allowed).
First write down percentage of lines that need to be replaced in the file (between 0-100) in percentage_to_change
percentage_to_change should be low if mostly new code is to be added. It should be high if a lot of things are to be replaced.
If percentage_to_change > 50, provide full file content in text_or_search_replace_blocks
If percentage_to_change <= 50, text_or_search_replace_blocks should be search/replace blocks.
Instructions for editing files.
Example
Input file
import numpy as np
from impls import impl1, impl2
def hello():
"print a greeting"
print("hello")
def call_hello():
"call hello"
hello()
print("Called")
impl1()
hello()
impl2()
Edit format on the input file
<<<<<<< SEARCH
from impls import impl1, impl2
=======
from impls import impl1, impl2
from hello import hello as hello_renamed
>>>>>>> REPLACE
<<<<<<< SEARCH
def hello():
"print a greeting"
print("hello")
=======
>>>>>>> REPLACE
<<<<<<< SEARCH
def call_hello():
"call hello"
hello()
=======
def call_hello_renamed():
"call hello renamed"
hello_renamed()
>>>>>>> REPLACE
<<<<<<< SEARCH
impl1()
hello()
impl2()
=======
impl1()
hello_renamed()
impl2()
>>>>>>> REPLACESEARCH/REPLACE block Rules:
Every "<<<<<<< SEARCH" section must EXACTLY MATCH the existing file content, character for character, including all comments, docstrings, whitespaces, etc.
Including multiple unique SEARCH/REPLACE blocks if needed. Include enough and only enough lines in each SEARCH section to uniquely match each set of lines that need to change.
Keep SEARCH/REPLACE blocks concise. Break large SEARCH/REPLACE blocks into a series of smaller blocks that each change a small portion of the file. Include just the changing lines, and a few surrounding lines (0-3 lines) if needed for uniqueness. Other than for uniqueness, avoid including those lines which do not change in search (and replace) blocks. Target 0-3 non trivial extra lines per block.
Preserve leading spaces and indentations in both SEARCH and REPLACE blocks.
Inputs: file_path (required), thread_id (required), percentage_to_change (required), text_or_search_replace_blocks (required).
InitializeARead-only
Always call this at the start of the conversation before using any of the shell tools from wcgw.
Use
any_workspace_pathto initialize the shell in the appropriate project directory.If the user has mentioned a workspace or project root or any other file or folder use it to set
any_workspace_path.If user has mentioned any files use
initial_files_to_readto read, use absolute paths only (~ allowed)By default use mode "wcgw"
In "code-writer" mode, set the commands and globs which user asked to set, otherwise use 'all'.
Use type="first_call" if it's the first call to this tool.
Use type="user_asked_mode_change" if in a conversation user has asked to change mode.
Use type="reset_shell" if in a conversation shell is not working after multiple tries.
Use type="user_asked_change_workspace" if in a conversation user asked to change workspace
Inputs: type (required), mode_name (required), thread_id (required), task_id_to_resume (required), +4 more.
ReadFilesARead-only
Read full file content of one or more files.
Use the thread_id returned by Initialize for this conversation when available; legacy clients may omit it.
Provide absolute paths only (~ allowed)
Only if the task requires line numbers understanding:
You may extract a range of lines. E.g.,
/path/to/file:1-10for lines 1-10. You can drop start or end like/path/to/file:1-or/path/to/file:-10
Inputs: file_paths (required), thread_id.
ReadImageBRead-only
Read an image from the shell. Use the thread_id returned by Initialize when available; legacy clients may omit it.
Inputs: file_path (required), thread_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool serves a clearly distinct role: initialize the session, run shell commands, read text files, read images, write/edit files, and save context. The small amount of overlap between BashCommand and the file tools is explicitly resolved by usage rules that forbid echo/cat for reading and writing.
All names are PascalCase and generally readable, but the pattern is mixed: ReadFiles and ReadImage are verb-noun, ContextSave and FileWriteOrEdit are noun-verb, BashCommand is noun-like, and Initialize is a bare verb. The inconsistency is noticeable but not chaotic.
Six tools is a well-scoped count for a shell/file-oriented MCP server. Each tool earns its place, and the set is neither bloated nor too thin for its apparent purpose.
The server covers the core workspace lifecycle: initialization, command execution, file reading, image reading, file writing/editing, and context saving. Generic operations like listing, deleting, or renaming are delegated to BashCommand, which works but makes for a slight indirectness rather than a true gap.
Maintenance
Related MCP Connectors
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Related MCP Servers
- AlicenseAqualityBmaintenanceA fully featured coding agent that uses symbolic operations (enabled by language servers) and works well even in large code bases. Essentially a free to use alternative to Cursor and Windsurf Agents, Cline, Roo Code and others.2931,250 PyPI31,560GPL 3.0
- FlicenseNot gradedqualityDmaintenanceEnables programmatic execution of coding tasks and autonomous file operations using Claude AI. It allows agents to search codebases, run shell commands, and track file changes through the Model Context Protocol.-
- AlicenseNot gradedqualityDmaintenanceProvides AI-driven development tools including file system operations, multi-language code analysis with tree-sitter, Git operations, code execution, and system information retrieval.MIT
- AlicenseNot gradedqualityCmaintenanceGives any MCP-compatible AI chat or agent a safe, model-neutral coding runtime with file read/search, structured multi-file patches, command execution, interactive sessions, and git operations, all confined to a single workspace and gated by permission modes.Apache 2.0