用于 Claude 和其他 MCP 客户端的 Shell 与编码代理

赋能聊天应用程序在你的本地机器上进行编码、构建和运行。

wcgw 是一个集成了 Shell 和代码编辑工具的 MCP 服务器。

⚠️ 警告：此 MCP 服务器提供对你机器 Shell 和文件的无限制访问。它不会限制 LLM 执行任意命令或进行意外更改。如果 AI 产生幻觉，此工具可能会被攻击者滥用或运行危险命令。仅在你完全理解并接受在无限制情况下运行 AI 代理的相关风险时，才运行此存储库。

截至 2026 年，你可以使用 wcgw 的原因是它提供了完全交互式的 Shell 体验，你和代理都可以控制它（包括发送按键）。 结合将代理的 Shell 附加到编辑器中的 wcgw VS Code 扩展，你可以获得目前市面上最好的代理 Shell 体验。 文件编辑技巧和整体的极简主义也有助于提高代理的工作效率。

👁 Tests
👁 Mypy strict
👁 Build
👁 codecov

演示

👁 Workflow Demo

Related MCP server: Global MCP Manager

更新

• [2025年10月6日] 模型现在可以在后台运行多个命令。ZSH 现在是受支持的 Shell。多路复用改进。

• [2025年4月27日] 移除了对通过中继服务器使用 GPT 的支持。版本 >= 5 仅支持 MCP 服务器。

• [2025年3月24日] 改进了 sonnet 3.7 的编写和编辑体验，CLAUDE.md 会自动加载。

• [2025年2月16日] 你现在可以附加到 AI 使用的工作终端。请参阅下方的“附加到终端”部分。

• [2025年1月15日] 引入了模式：architect、code-writer 和功能强大的 wcgw 模式。

• [2025年1月8日] 上下文保存工具，用于将相关文件路径及其描述保存在单个文件中。可用作任务检查点或知识转移。

• [2024年12月29日] 文件写入和编辑时的语法检查现已稳定。使 initialize 工具调用变得有用；如果引用了任何存储库，则向 Claude 发送智能存储库结构。大文件处理也得到了改进。

• [2024年12月9日] 用于在 Claude 应用上粘贴上下文的 VS Code 扩展

🚀 亮点

• ⚡ 创建、执行、迭代：要求 Claude 不断运行编译器检查，直到修复所有错误，或者要求它不断检查长时间运行的命令的状态，直到完成。

• ⚡ 大文件编辑：支持大文件增量编辑，以避免 Token 限制问题。根据所需的更改百分比，智能选择进行小幅编辑还是大幅重写。

• ⚡ 编辑时的语法检查：如果编辑存在任何语法错误，会向 LLM 反馈，以便其重新执行。

• ⚡ 交互式命令处理：支持使用箭头键、中断和 ANSI 转义序列的交互式命令。

• ⚡ 文件保护：

  • AI 在被允许编辑或重写文件之前，必须至少读取一次该文件。这避免了意外覆盖。

  • 读取超大文件时避免上下文填满。文件根据 Token 长度进行分块。

  • 初始化时，在选择重要文件（基于 .gitignore 以及统计方法）后，返回所提供工作区的目录结构。

  • 基于搜索-替换的文件编辑会尝试根据之前的搜索块找到正确的搜索块。否则失败（为了正确性）。

  • 文件编辑具有空格容错匹配功能，并在缩进不匹配等问题上发出警告。如果没有匹配项，则将最接近的匹配项返回给 AI 以修复其错误。

  • 使用类似 Aider 的搜索和替换，其性能优于基于工具调用的搜索和替换。

• ⚡ Shell 优化：

  • 任何 Shell 命令后都会始终返回当前工作目录，以防止 AI 迷失方向。

  • 命令轮询在快速超时后退出，以避免反馈缓慢。但是，状态检查具有基于命令新鲜输出流的等待容忍度。这两种方法结合在一起提供了良好的 Shell 交互体验。

  • 支持在主交互式 Shell 之外同时运行多个后台命令。

• ⚡ 将存储库上下文保存在单个文件中：使用 "ContextSave" 工具进行任务检查点设置，将详细上下文保存在单个文件中。任务稍后可以在新的聊天中通过要求 "Resume task id" 来恢复。保存的文件可用于进行其他类型的知识转移，例如从另一个 AI 获取帮助。

• ⚡ 轻松切换各种模式：

  • 要求它在 'architect' 模式下运行以进行规划。受 Aider 架构师模式的启发，先与 Claude 一起制定计划。这能提高准确性并防止过早编辑文件。

  • 要求它在 'code-writer' 模式下运行以进行代码编辑和项目构建。你可以提供带有通配符支持的特定路径，以防止其他文件被编辑。

  • 默认情况下，它在 'wcgw' 模式下运行，该模式没有任何限制且具有完全授权。

  • 更多详细信息请参阅 模式部分

• ⚡ 在多路复用终端中运行：使用 VS Code 扩展 或运行 screen -x 来附加到 AI 运行命令的终端。查看历史记录、中断进程或与 AI 使用的相同终端进行交互。

• ⚡ 自动加载 CLAUDE.md/AGENTS.md：加载项目根目录中的 "CLAUDE.md" 或 "AGENTS.md" 文件，并在初始化期间作为指令发送。全局 "/.wcgw/AGENTS.md" 文件中的指令会被加载，并与项目特定的 CLAUDE.md 一起添加。文件名区分大小写。如果存在 CLAUDE.md 则附加它，否则附加 AGENTS.md。

Claude 设置（使用 MCP）

Mac 和 Linux

首先使用 Homebrew 安装 uv：brew install uv

(重要：使用 Homebrew 安装 uv。否则请确保 uv 存在于全局位置，如 /usr/bin/)

然后使用以下 JSON 创建或更新 claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json)。

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

然后重启 Claude 应用。

可选：强制使用特定 Shell

要使用特定 Shell（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 文件夹。

• 尝试使用此工具测试过的 uv 版本 0.6.0。

• 使用 npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw 调试 MCP 服务器。

Windows 上的 WSL

此 MCP 服务器仅在 Windows 的 WSL 上工作。

要进行设置，请 安装 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 的正确路径。

1. 查找 uv 的安装位置：

whereis uv

示例输出： uv: /home/mywsl/.local/bin/uv

2. 测试完整路径是否有效：

wsl /home/mywsl/.local/bin/uv tool run --python 3.12 wcgw

3. 使用完整路径更新配置：

{
 "mcpServers": {
 "wcgw": {
 "command": "wsl.exe",
 "args": ["/home/mywsl/.local/bin/uv", "tool", "run", "--python", "3.12", "wcgw"]
 }
 }
}

将 /home/mywsl/.local/bin/uv 替换为步骤 1 中你的实际 uv 路径。

使用方法

等待几秒钟。如果一切顺利，你应该能看到此图标。

👁 mcp icon
在这里

👁 mcp icon

然后要求 Claude 执行 Shell 命令、读取文件、编辑文件、运行代码等。

任务检查点或知识转移

• 你可以通过使用 "Attach from MCP" 按钮附加 "KnowledgeTransfer" 提示词来进行任务检查点设置或知识转移。

• 运行 "KnowledgeTransfer" 提示词时，将调用 "ContextSave" 工具，将任务描述和所有文件内容保存在单个文件中。将生成一个任务 ID。

• 你可以在新的聊天中说 "Resume ''"，AI 随后应使用任务 ID 调用 "Initialize" 并从那里加载上下文。

• 或者，你可以直接打开生成的文件并将其分享给另一个 AI 以获取帮助。

模式

有三种内置模式。你可以要求 Claude 在其中一种模式下运行，例如 "Use 'architect' mode"

注意：在 code-writer 模式下，目前要么允许所有命令，要么都不允许。如果你提供了一份允许的命令列表，Claude 会被指示仅运行这些命令，但实际上不会进行检查。（正在开发中）

附加到工作终端进行调查

新功能：VS Code 扩展 现在会在工作区路径匹配时自动附加正在运行的终端。

如果你安装了 screen 命令，wcgw 会自动在 screen 实例上运行。如果你已经启动了 wcgw MCP 服务器，你可以列出 screen 会话：

screen -ls

并记下 wcgw screen 名称，它看起来像 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 并粘贴包含你的指令、文件路径、工作区目录和所选文本的内容。

示例

👁 example

通过 Docker 使用 MCP 服务器

首先构建 Docker 镜像 docker build -t wcgw https://github.com/rusiaaman/wcgw.git

然后你可以更新 /Users/username/Library/Application Support/Claude/claude_desktop_config.json 以包含

{
 "mcpServers": {
 "wcgw": {
 "command": "docker",
 "args": [
 "run",
 "-i",
 "--rm",
 "--mount",
 "type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
 "wcgw"
 ]
 }
 }
}

工具

服务器提供以下 MCP 工具：

Shell 操作：

• Initialize：重置 Shell 并设置工作区环境

  • 参数：any_workspace_path (string), initial_files_to_read (string[]), mode_name ("wcgw"|"architect"|"code_writer"), task_id_to_resume (string)

• BashCommand：执行带有超时控制的 Shell 命令

  • 参数：command (string), wait_for_seconds (int, optional)

  • 参数：send_text (string) 或 send_specials (["Enter"|"Key-up"|...]) 或 send_ascii (int[]), wait_for_seconds (int, optional)

文件操作：

• ReadFiles：读取一个或多个文件的内容

  • 参数：file_paths (string[])

• WriteIfEmpty：创建新文件或写入空文件

  • 参数：file_path (string), file_content (string)

• FileEdit：使用搜索/替换块编辑现有文件

  • 参数：file_path (string), file_edit_using_search_replace_blocks (string)

• ReadImage：读取图像文件以进行显示/处理

  • 参数：file_path (string)

项目管理：

• ContextSave：保存项目上下文和文件以进行知识转移或保存任务检查点以便稍后恢复

  • 参数：id (string), project_root_path (string), description (string), relevant_file_globs (string[])

所有工具都支持绝对路径，并包含针对常见错误的内置保护。有关详细的协议信息，请参阅 MCP 规范

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• BashCommandA
• ContextSaveC
• FileWriteOrEditA
• InitializeA
• ReadFilesA
• ReadImageC