wcgw

Name: wcgw
Author: Aman Rusia

Local shell and file-editing MCP server that gives an assistant an interactive terminal on your machine

By Aman Rusia (individual) Python Local · stdio Developer tools Files and storage

GitHub PyPI Website

0 popularity score ★ 678

Connect your client

Local (PyPI)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add wcgw -- uvx --python 3.12 wcgw@latest

Claude Desktopclaude_desktop_config.json

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

Cursor~/.cursor/mcp.json

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

VS Code.vscode/mcp.json

{
  "servers": {
    "wcgw": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "wcgw@latest"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.wcgw]
command = "uvx"
args = ["--python", "3.12", "wcgw@latest"]

Gemini CLITerminal

gemini mcp add --scope user wcgw uvx -- --python 3.12 wcgw@latest

Local (container)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

FirstTerminal

docker build -t wcgw https://github.com/rusiaaman/wcgw.git

Claude CodeTerminal

claude mcp add wcgw -- docker run -i --rm --mount 'type=bind,src=<ABSOLUTE_PATH>,dst=/workspace/project' wcgw

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "wcgw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=<ABSOLUTE_PATH>,dst=/workspace/project",
        "wcgw"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "wcgw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=<ABSOLUTE_PATH>,dst=/workspace/project",
        "wcgw"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "wcgw": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=<ABSOLUTE_PATH>,dst=/workspace/project",
        "wcgw"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.wcgw]
command = "docker"
args = ["run", "-i", "--rm", "--mount", "type=bind,src=<ABSOLUTE_PATH>,dst=/workspace/project", "wcgw"]

Gemini CLITerminal

gemini mcp add --scope user wcgw docker -- run -i --rm --mount 'type=bind,src=<ABSOLUTE_PATH>,dst=/workspace/project' wcgw

What it does

wcgw runs on your own computer and hands an MCP client a persistent, stateful shell plus tools to read, create and edit files. It is aimed at coding work: the assistant can build a project, run a compiler or test suite, read the errors and edit the code again in a loop, and it can poll long-running commands instead of waiting on them. The shell is interactive, so the assistant can send keystrokes, arrow keys, Ctrl-C or raw ASCII codes to programs that prompt for input, and since October 2025 it can keep several commands running in the background next to the main shell. Bash and zsh are supported.

File edits go through one tool that takes either search/replace blocks or a full rewrite depending on how much of the file changes; edits are checked for syntax errors and the result is fed back. A file has to be read before it can be overwritten. On start-up the server returns a trimmed view of the workspace tree and loads CLAUDE.md or AGENTS.md from the project root and from ~/.wcgw/. A ContextSave tool writes a task description and the contents of chosen files into one text file, which a later chat can resume from by its id.

It has three modes: the default 'wcgw' mode with no restrictions, a read-only 'architect' mode for planning, and a 'code_writer' mode limited to path globs. When GNU screen is installed the shell runs inside a screen session that you can attach to (or view through the author's VS Code extension) to watch or interrupt what the assistant does.

The tool list in the README is out of date: at version 5.6.7 the server registers six tools, and the separate WriteIfEmpty and FileEdit tools it describes are merged into one FileWriteOrEdit tool (src/wcgw/client/tool_prompts.py). Tool output is truncated at 24,000 tokens for coding tools and 8,000 for others (server.py).

What it needs

Runtime	Python 3.12+
Runs on	macOS, Linux
Also	uv installed globally so the client finds uvx GNU screen, optional, to attach to the shell

uv (the docs ask for a global install, e.g. via Homebrew, so the client can find uvx) and Python 3.12, which the launch command requests. macOS or Linux; on Windows it runs only inside WSL. GNU screen is optional and needed only to attach to the assistant's terminal. The Docker way needs Docker and a locally built image. No account or API key.

Limits

Platform Runs on macOS and Linux. On Windows it works only inside WSL.
Not covered In code_writer mode the allowed command list is passed to the assistant as an instruction and is not checked. The path globs are what the mode enforces.
Not covered One foreground command runs at a time. Each background command gets a fresh shell that cannot be reused.
Size cap Tool output is cut at 24,000 tokens for coding tools and 8,000 for others per call (server.py at 5.6.7).
Limit The README still names WriteIfEmpty and FileEdit tools. At 5.6.7 FileWriteOrEdit replaces both.
Limit Streamable HTTP is opt-in with --transport streamable-http and binds to 127.0.0.1:8765 unless --host and --port are given.
Limit No Docker image is published. You build it yourself from the repository.
Limit The GitHub repository is archived, so further fixes are unlikely.

Windows is supported only through WSL. In code_writer mode a list of allowed commands is only passed to the assistant as an instruction and is not checked; file path globs are what the mode enforces. Only one foreground command runs at a time; each background command gets a fresh shell that cannot be reused. Tool output is cut at 24,000 tokens (coding) or 8,000 tokens (other) per call. The README's tool list names WriteIfEmpty and FileEdit, which no longer exist at 5.6.7; FileWriteOrEdit replaces both. Streamable HTTP is opt-in with --transport streamable-http and binds to 127.0.0.1:8765 unless --host and --port are given. The Docker image is not published; you build it yourself.

Who it suits

Suits a developer who wants Claude Desktop or another MCP client to work as a hands-on coding agent on their own machine, with a real interactive terminal they can attach to and take over. Because it runs arbitrary commands with your user's rights and has no restrictions in its default mode, it is a poor fit for untrusted prompts or shared machines; there, run it in the Docker container with only a project folder mounted, or use architect mode for read-only exploration. Someone who only needs file reads and writes without a shell is better served by a narrower file-system server.

Tools 6

3 only read, 1 changes things, 2 can delete or overwrite. A ? marks an optional parameter.

Initialize: Starts or resets the shell in a workspace, picks the mode, can read starting files or resume a saved tasktype: enumany_workspace_path: stringinitial_files_to_read: arraytask_id_to_resume: stringmode_name: enumthread_id: stringallowed_globs?: anyallowed_commands?: any
BashCommand deletes: Runs a shell command, checks its status, sends text or keystrokes, or manages background commandstype: enumcommand?: stringstatus_check?: booleansend_text?: stringsend_specials?: arraysend_ascii?: arrayis_background?: booleanbg_command_id?: stringwait_for_seconds?: numberthread_id: string
ReadFiles: Returns the contents of one or more files, with an optional line range written after the pathfile_paths: arraythread_id?: string
ReadImage: Returns an image file so the assistant can view itfile_path: stringthread_id?: string
FileWriteOrEdit deletes: Creates a file or edits one by search/replace blocks or full rewrite, with a syntax checkfile_path: stringpercentage_to_change: integertext_or_search_replace_blocks: stringthread_id: string
ContextSave changes: Saves a task description and the contents of matching files into one text file for later resumptionid: stringproject_root_path: stringdescription: stringrelevant_file_globs: arraythread_id?: string

Prompts 1

KnowledgeTransfer: Asks the assistant to save the current task, errors and instructions with ContextSave

Popularity

0 popularity score

★ 678

GitHub stars	678	34 points
Stars in 30 days	+0	0 points
PyPI downloads, last month	0
Activity	Archived or deprecated	× 0

Measured 2026-11-07. How the score works.

Where it is published

Code	rusiaaman/wcgw ★ 678
PyPI	3-12
PyPI	wcgw

What it can reach

Runs	On your machine
Reaches	Runs shell commands, Files on your machine, Your code, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	Apache-2.0 (GitHub)
Latest version	5.6.6 GitHub release, 2026-09-12
Last code change	2026-09-12
Status	Archived by its maker

Runs on your machine with your user's permissions. BashCommand executes any shell command, so the assistant can reach whatever your account can, including the network, and FileWriteOrEdit creates and changes files at any absolute path. Its makers warn that it gives unfiltered shell and file access, does not stop the model from running arbitrary or harmful commands, and should be used only by people who accept those risks. The default 'wcgw' mode has no restrictions; architect mode denies file edits and code_writer limits edits to path globs, but its command allow-list is not enforced. No sign-in is needed. The optional HTTP transport binds to 127.0.0.1 by default. ContextSave writes file contents into a single text file on disk.

Over time

GitHub stars 678 +0

678677

9 Oct 20267 Nov 2026

PyPI downloads a month

History building since 9 Oct 2026: a chart appears once a week of points is in.

Popularity score 0 −57 (−100 %)

570

9 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-29.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![wcgw on EveryMCPServer](https://everymcpserver.com/badge/wcgw.svg)](https://everymcpserver.com/servers/wcgw)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

What it does

What it needs

Limits

Who it suits

Tools 6

Prompts 1

Similar servers

Desktop Commander MCP

FastCtx

computer-use-linux

Token Optimizer MCP

Entroly

BC Code Intelligence MCP Server