mcp-wcgw
Агент для работы с оболочкой и кодом для Claude и других MCP-клиентов
Предоставление чат-приложениям возможности писать код, собирать и запускать его на вашей локальной машине.
wcgw — это MCP-сервер с тесно интегрированными инструментами оболочки и редактирования кода.
⚠️ Предупреждение: Этот MCP-сервер предоставляет нефильтрованный доступ к оболочке и файлам вашей машины. Он не ограничивает LLM в выполнении произвольных команд или внесении непреднамеренных изменений. Этот инструмент может быть использован злоумышленниками или для выполнения опасных команд в случае галлюцинаций ИИ. Запускайте этот репозиторий только в том случае, если вы полностью понимаете и принимаете риски, связанные с запуском ИИ-агентов без ограничений.
По состоянию на 2026 год причина, по которой вы можете использовать wcgw, заключается в том, что он предоставляет полностью интерактивный опыт работы с оболочкой, который можете контролировать вы и агент (включая отправку нажатий клавиш).
В сочетании с расширением wcgw для vscode, которое подключает оболочку агента к вашему редактору, вы можете получить лучший опыт работы с агентской оболочкой из существующих.
Трюки с редактированием файлов и общий минимализм также помогают агенту быть более продуктивным.
Демо

Related MCP server: Claude Code Control MCP
Обновления
[6 окт. 2025 г.] Модель теперь может запускать несколько команд в фоновом режиме. ZSH теперь является поддерживаемой оболочкой. Улучшения мультиплексирования.
[27 апр. 2025 г.] Удалена поддержка GPT через ретрансляционный сервер. В версии >= 5 поддерживается только MCP-сервер.
[24 мар. 2025 г.] Улучшен опыт написания и редактирования для sonnet 3.7, CLAUDE.md загружается автоматически.
[16 февр. 2025 г.] Теперь вы можете подключиться к рабочему терминалу, который использует ИИ. См. раздел "attach-to-terminal" ниже.
[15 янв. 2025 г.] Введены режимы: архитектор, разработчик (code-writer) и всемогущий режим wcgw.
[8 янв. 2025 г.] Инструмент сохранения контекста для сохранения соответствующих путей к файлам вместе с описанием в одном файле. Может использоваться как контрольная точка задачи или для передачи знаний.
[29 дек. 2024 г.] Проверка синтаксиса при записи и редактировании файлов теперь стабильна. Сделан полезным вызов инструмента
initialize; отправка структуры умного репозитория в claude, если ссылается какой-либо репозиторий. Также улучшена обработка больших файлов.[9 дек. 2024 г.] Расширение Vscode для вставки контекста в приложение Claude
🚀 Основные моменты
⚡ Создание, выполнение, итерация: Попросите claude продолжать выполнять проверки компилятора, пока все ошибки не будут исправлены, или попросите его продолжать проверять статус долго выполняющейся команды, пока она не завершится.
⚡ Редактирование больших файлов: Поддерживает инкрементальное редактирование больших файлов, чтобы избежать проблем с лимитом токенов. Умный выбор между небольшими правками или полной перезаписью на основе % необходимых изменений.
⚡ Проверка синтаксиса при правках: Сообщает LLM, если в ее правках есть синтаксические ошибки, чтобы она могла их переделать.
⚡ Интерактивная обработка команд: Поддерживает интерактивные команды с использованием клавиш со стрелками, прерывания и escape-последовательностей ansi.
⚡ Защита файлов:
ИИ должен прочитать файл хотя бы один раз, прежде чем ему будет разрешено редактировать или перезаписывать его. Это предотвращает случайную перезапись.
Предотвращает заполнение контекста при чтении очень больших файлов. Файлы разбиваются на части в зависимости от длины токена.
При инициализации возвращается структура каталогов предоставленного рабочего пространства после выбора важных файлов (на основе .gitignore, а также статистического подхода).
Редактирование файлов на основе поиска-замены пытается найти правильный блок поиска, если он имеет несколько совпадений на основе предыдущих блоков поиска. В противном случае выдает ошибку (для корректности).
Редактирование файлов имеет сопоставление с допуском к пробелам, с предупреждением о таких проблемах, как несоответствие отступов. Если совпадений нет, ближайшее совпадение возвращается ИИ для исправления ошибок.
Используется поиск и замена в стиле Aider, который имеет лучшую производительность, чем поиск и замена на основе вызова инструментов.
⚡ Оптимизация оболочки:
Текущий рабочий каталог всегда возвращается после любой команды оболочки, чтобы ИИ не терялся.
Опрос команд завершается после быстрого тайм-аута, чтобы избежать медленной обратной связи. Однако проверка статуса имеет допуск ожидания, основанный на потоковой передаче свежих выходных данных от команды. Оба этих подхода в сочетании обеспечивают хороший опыт взаимодействия с оболочкой.
Поддерживает несколько одновременных фоновых команд наряду с основной интерактивной оболочкой.
⚡ Сохранение контекста репозитория в одном файле: Контрольные точки задач с использованием инструмента "ContextSave" сохраняют подробный контекст в одном файле. Задачи позже можно возобновить в новом чате, попросив "Resume
task id". Сохраненный файл можно использовать для других видов передачи знаний, например, для получения помощи от другого ИИ.⚡ Легкое переключение между различными режимами:
Попросите его работать в режиме 'architect' для планирования. Вдохновленный режимом архитектора adier, сначала работайте с Claude, чтобы составить план. Это приводит к большей точности и предотвращает преждевременное редактирование файлов.
Попросите его работать в режиме 'code-writer' для редактирования кода и сборки проекта. Вы можете указать конкретные пути с поддержкой подстановочных знаков, чтобы предотвратить редактирование других файлов.
По умолчанию он работает в режиме 'wcgw', который не имеет ограничений и обладает полной авторизацией.
Подробнее в разделе Режимы
⚡ Запуск в мультиплексном терминале: Используйте расширение vscode или запустите
screen -x, чтобы подключиться к терминалу, в котором ИИ выполняет команды. Просматривайте историю, прерывайте процессы или взаимодействуйте с тем же терминалом, который использует ИИ.⚡ Автоматическая загрузка CLAUDE.md/AGENTS.md: Загружает файл "CLAUDE.md" или "AGENTS.md" в корне проекта и отправляет его в качестве инструкций во время инициализации. Инструкции в глобальном файле "
/.wcgw/CLAUDE.md" или "/.wcgw/AGENTS.md" загружаются и добавляются вместе с CLAUDE.md, специфичным для проекта. Имя файла чувствительно к регистру. CLAUDE.md прикрепляется, если он присутствует, в противном случае прикрепляется AGENTS.md.
Настройка Claude (с использованием mcp)
Mac и linux
Сначала установите uv с помощью homebrew brew install uv
(Важно: используйте homebrew для установки uv. В противном случае убедитесь, что uv присутствует в глобальном расположении, например /usr/bin/)
Затем создайте или обновите claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json) с помощью следующего json.
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["--python", "3.12", "wcgw@latest"]
}
}
}Затем перезапустите приложение claude.
Дополнительно: Принудительное использование определенной оболочки
Чтобы использовать определенную оболочку (bash или zsh), добавьте аргумент --shell:
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": ["--python", "3.12", "wcgw@latest", "--shell", "/bin/bash"]
}
}
}Если возникла ошибка при настройке
Если возникла ошибка типа "uv ENOENT", убедитесь, что
uvустановлен. Затем выполните 'which uv' в терминале и используйте его вывод вместо "uv" в конфигурации.Если проблема сохраняется, проверьте, что
uv tool run --python 3.12 wcgwзапускается в вашем терминале. Он не должен выдавать вывод и не должен завершаться.Попробуйте удалить папку ~/.cache/uv
Попробуйте использовать версию
uv0.6.0, на которой тестировался этот инструмент.Отладьте mcp-сервер с помощью
npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw
Windows в wsl
Этот mcp-сервер работает только в wsl на windows.
Чтобы настроить его, установите uv
Затем добавьте или обновите файл конфигурации claude %APPDATA%\Claude\claude_desktop_config.json следующим образом
{
"mcpServers": {
"wcgw": {
"command": "wsl.exe",
"args": ["uvx", "--python", "3.12", "wcgw@latest"]
}
}
}Когда вы столкнетесь с ошибкой, выполните команду wsl uv --python 3.12 wcgw в командной строке. Если вы получили error /bin/bash: line 1: uv: command not found, это означает, что uv не был установлен глобально, и вам нужно указать правильный путь к uv.
Найдите, где установлен uv:
whereis uvПример вывода:
uv: /home/mywsl/.local/bin/uv
Проверьте, работает ли полный путь:
wsl /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"]
}
}
}Замените /home/mywsl/.local/bin/uv на ваш фактический путь к uv из шага 1.
Использование
Подождите несколько секунд. Вы должны увидеть этот значок, если все сделано правильно.
здесь

Затем попросите claude выполнять команды оболочки, читать файлы, редактировать файлы, запускать ваш код и т. д.
Контрольная точка задачи или передача знаний
Вы можете создать контрольную точку задачи или передать знания, прикрепив подсказку "KnowledgeTransfer" с помощью кнопки "Attach from MCP".
При запуске подсказки "KnowledgeTransfer" будет вызван инструмент "ContextSave", сохраняющий описание задачи и все содержимое файлов вместе в одном файле. Будет сгенерирован идентификатор задачи.
Вы можете в новом чате сказать "Resume ''", ИИ должен затем вызвать "Initialize" с идентификатором задачи и загрузить контекст оттуда.
Или вы можете напрямую открыть созданный файл и поделиться им с другим ИИ для получения помощи.
Режимы
Существует три встроенных режима. Вы можете попросить Claude работать в одном из режимов, например "Use 'architect' mode"
Режим | Описание | Разрешает | Запрещает | Вызов подсказки |
Architect | Разработан для того, чтобы вы могли работать с Claude для исследования и понимания вашего репозитория. | Команды только для чтения | Инструменты FileEdit и Write | Run in mode='architect' |
Code-writer | Для написания кода и разработки | Указанные пути для редактирования или записи, указанные команды | FileEdit для путей, не соответствующих указанному glob, Write для путей, не соответствующих указанному glob | Run in code writer mode, only 'tests/**' allowed, only uv command allowed |
wcgw | Режим по умолчанию, где разрешено все | Все | Ничего | Нет подсказки или "Run in wcgw mode" |
Примечание: в режиме code-writer на данный момент разрешены либо все команды, либо ни одной. Если вы предоставите список разрешенных команд, Claude получит инструкцию выполнять только эти команды, но фактическая проверка не выполняется. (В разработке)
Подключитесь к рабочему терминалу для исследования
НОВОЕ: расширение vscode теперь автоматически подключает запущенный терминал, если путь к рабочему пространству совпадает.
Если у вас установлена команда screen, wcgw автоматически запускается в экземпляре screen. Если вы запустили mcp-сервер wcgw, вы можете вывести список сеансов screen:
screen -ls
И запишите имя экрана wcgw, которое будет выглядеть примерно так: 93358.wcgw.235521, где последнее число указано в формате час-минута-секунда.
Затем вы можете подключиться к сеансу с помощью screen -x 93358.wcgw.235521
Вы можете безопасно прервать любую выполняемую команду.
Вы можете безопасно взаимодействовать с терминалом, например, для ввода паролей или ввода текста. (Предупреждение: если вы запустите новую команду, любая новая команда LLM прервет ее.)
Вам не следует выходить из сеанса с помощью exit или Ctrl-d, вместо этого вам следует использовать ctrl+a+d для безопасного отсоединения, не уничтожая сеанс screen.
Включите следующее в ~/.screenrc для лучшего опыта прокрутки
defscrollback 10000
termcapinfo xterm* ti@:te@[Дополнительно] Расширение Vs code
https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw
Команды:
Выделите текст и нажмите
cmd+', а затем введите инструкции. Это переключит приложение на Claude и вставит текст, содержащий ваши инструкции, путь к файлу, каталог рабочего пространства и выделенный текст.
Примеры

Использование mcp-сервера через docker
Сначала соберите образ docker docker build -t wcgw https://github.com/rusiaaman/wcgw.git
Затем вы можете обновить `/Users/username/Library/Application Support/Claude/claude_desktop_config.
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