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

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

wcgw 是一个与 shell 和代码编辑工具紧密集成的 MCP 服务器。

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

截至 2026 年，您可以使用 wcgw 的原因是它提供了完全交互式的 shell 体验，您和代理都可以控制（包括发送按键输入）。 结合将代理的 shell 挂载到您编辑器中的 wcgw VSCode 扩展，您可以获得目前市场上最佳的代理式 shell 体验。 文件编辑技巧和整体极简设计也有助于提高代理的工作效率。

演示

更新日志

• [2025年10月6日] 模型现在可以在后台运行多个命令。ZSH 现已成为支持的 shell。多路复用功能得到改进。

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

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

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

• [2025年1月15日] 引入了三种模式：架构师模式、代码编写模式以及全能的 wcgw 模式。

• [2025年1月8日] 提供了上下文保存工具，可将相关文件路径连同描述一起保存到单个文件中。可用作任务检查点或知识转移之用。

• [2024年12月29日] 文件写入和编辑时的语法检查现已稳定。使 initialize 工具调用变得更有用；当引用任何代码库时，会向 Claude 发送智能的代码库结构信息。同时，大文件处理能力也得到了提升。

• [2024年12月9日] VSCode 扩展可在 Claude 应用中粘贴上下文

🚀 亮点

• ⚡ 创建、执行、迭代: 您可以让 Claude 不断运行编译器检查，直到所有错误都被修复；或者让它持续监控长时间运行命令的状态，直到完成。
• ⚡ 大文件编辑: 支持大文件的增量编辑，以避免 token 限制问题。根据所需更改的比例，智能选择是进行小范围编辑还是大规模重写。
• ⚡ 编辑时的语法检查: 如果 LLM 的编辑存在语法错误，系统会反馈给它，以便其重新修改。
• ⚡ 交互式命令处理: 支持使用方向键、中断信号和 ANSI 转义序列的交互式命令。
• ⚡ 文件保护措施:
  • AI 必须至少读取一次文件后才能对其进行编辑或重写，从而避免意外覆盖。
  • 在读取超大文件时，避免上下文过载。文件会根据 token 长度进行分块。
  • 初始化时，会返回所提供工作区的目录结构，并从中挑选重要文件（基于 .gitignore 文件及统计方法）。
  • 基于搜索替换的文件编辑会尝试找到正确的搜索区域，即使有多个匹配项，也会根据之前的搜索结果来判断。否则将失败（以确保准确性）。
  • 文件编辑采用间距容错匹配机制，并会在缩进不一致等问题时发出警告。如果没有匹配项，则会返回最接近的匹配结果，供 AI 修正错误。
  • 使用类似 Aider 的搜索和替换功能，其性能优于基于工具调用的搜索和替换。
• ⚡ Shell 优化:
  • 每次执行 shell 命令后，都会返回当前工作目录，以防止 AI 迷失方向。
  • 命令轮询会在短暂超时后退出，以避免反馈延迟。然而，状态检查则会根据命令实时输出流调整等待时间。这两种方式相结合，能够提供良好的 shell 交互体验。
  • 支持在主交互式 shell 之外同时运行多个后台命令。
• ⚡ 将代码库上下文保存为单个文件: 使用“ContextSave”工具进行任务检查点保存，可将详细上下文保存到一个文件中。之后，您可以在新的对话中通过询问“Resume task id”来恢复任务。保存的文件也可用于其他形式的知识转移，例如让另一台 AI 提供帮助。
• ⚡ 轻松切换不同模式:
  • 您可以要求它以“架构师模式”进行规划。受 Aider 架构师模式启发，先与 Claude 合作制定计划，这样可以提高准确性并防止过早编辑文件。
  • 您也可以要求它以“代码编写模式”进行代码编辑和项目构建。您可以提供特定路径，并支持通配符，以防止其他文件被编辑。
  • 默认情况下，它以“wcgw 模式”运行，该模式没有任何限制且拥有完全授权。
  • 更多详情请参阅 模式章节。
• ⚡ 在多路复用终端中运行 使用 VSCode 插件 或运行 screen -x 来连接到 AI 执行命令的终端。您可以查看历史记录、中断进程，或与 AI 使用的同一终端进行交互。
• ⚡ 自动加载 CLAUDE.md/AGENTS.md 自动加载项目根目录下的“CLAUDE.md”或“AGENTS.md”文件，并在初始化时将其作为指令发送。此外，还会加载全局“/.wcgw/CLAUDE.md”或“/.wcgw/AGENTS.md”文件的内容，并与项目特定的 CLAUDE.md 一同添加。文件名区分大小写。如果存在 CLAUDE.md，则会附加该文件；否则将附加 AGENTS.md。

使用 MCP 设置 Claude

Mac 和 Linux

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

（重要提示：请务必使用 Homebrew 安装 uv。否则，请确保 uv 已安装在全局路径下，例如 /usr/bin/。）

然后创建或更新 claude_desktop_config.json 文件（路径为 ~/Library/Application Support/Claude/claude_desktop_config.json），内容如下：

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

接着重启 Claude 应用程序。

可选：强制指定特定的 Shell

如果需要使用特定的 Shell（如 bash 或 zsh），可以在配置中添加 --shell 参数：

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": ["wcgw@latest", "--shell", "/bin/bash"]
    }
  }
}

如果在设置过程中出现错误

• 如果出现类似 uv ENOENT 的错误，请确认 uv 是否已正确安装。然后在终端运行 which uv，将输出结果替换配置中的 uv。
• 如果问题仍然存在，请检查是否能在终端成功运行 uv tool run --python 3.12 wcgw。该命令应无任何输出且不会退出。
• 尝试删除 ~/.cache/uv 文件夹。
• 尝试使用版本 0.6.0 的 uv，因为本工具正是基于该版本测试的。
• 使用以下命令调试 MCP 服务器：npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw。

Windows 上的 WSL

此 MCP 服务器仅适用于 Windows 上的 WSL 环境。

要进行设置，请先安装 uv。

然后编辑或更新 Claude 配置文件 %APPDATA%\Claude\claude_desktop_config.json，内容如下：

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["uvx", "wcgw@latest"]
    }
  }
}

遇到错误时，在命令提示符中执行 wsl uv --python 3.12 wcgw 命令。如果出现 /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 替换为你实际的 uv 路径。

使用方法

等待几秒钟后，如果一切正常，你应该能看到如下图标：

在此处

随后你可以让 Claude 执行 Shell 命令、读取文件、编辑文件、运行代码等操作。

任务检查点或知识转移

• 你可以通过点击“从 MCP 附加”按钮来附加“KnowledgeTransfer”提示，从而实现任务检查点或知识转移。
• 当运行“KnowledgeTransfer”提示时，“ContextSave”工具会被调用，将任务描述和所有文件内容保存到一个单独的文件中，并生成一个任务 ID。
• 在新的对话中，你可以说“恢复 '<任务ID>'”，AI 将会调用“Initialize”并加载相应的上下文。
• 或者直接打开生成的文件，将其分享给其他 AI 寄托处理。

模式

内置三种模式。你可以要求 Claude 切换到其中一种模式，例如“使用 'architect' 模式”。

模式	描述	允许	拒绝	调用提示
Architect	专为与 Claude 合作调查和理解你的代码库而设计。	只读命令	禁止 FileEdit 和 Write 工具	运行模式='architect'
Code-writer	用于代码编写和开发	允许编辑或写入指定路径的文件，以及执行指定命令	禁止编辑或写入不符合指定 glob 模式的路径	运行代码编写模式，仅允许 'tests/**' 路径，且仅限使用 uv 命令
wcgw**	默认模式，所有功能均开放	全部开放	无限制	不需提示，或直接说“切换到 wcgw 模式”

注意：目前在代码编写模式下，要么所有命令都允许，要么全部禁止。如果你提供允许的命令列表，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，并粘贴包含你的指令、文件路径、工作区目录以及所选文本的内容。

示例

通过 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（字符串）、initial_files_to_read（字符串数组）、mode_name（“wcgw”、“architect”或“code_writer”）、task_id_to_resume（字符串）
• BashCommand：执行带有超时控制的 Shell 命令
  • 参数：command（字符串）、wait_for_seconds（整数，可选）
  • 参数：send_text（字符串）或 send_specials（[“Enter”、“Key-up”等]）或 send_ascii（整数数组）、wait_for_seconds（整数，可选）

文件操作：

• ReadFiles：从一个或多个文件中读取内容
  • 参数：file_paths（字符串数组）
• WriteIfEmpty：创建新文件或将内容写入空文件
  • 参数：file_path（字符串）、file_content（字符串）
• FileEdit：使用搜索/替换块编辑现有文件
  • 参数：file_path（字符串）、file_edit_using_search_replace_blocks（字符串）
• ReadImage：读取图像文件以供显示或处理
  • 参数：file_path（字符串）

项目管理：

• ContextSave：保存项目上下文和文件，用于知识转移或保存任务检查点以便后续恢复
  • 参数：id（字符串）、project_root_path（字符串）、description（字符串）、relevant_file_globs（字符串数组）

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

wcgw 快速上手指南

wcgw 是一个专为 Claude 及其他 MCP 客户端设计的 Shell 和代码代理服务器。它赋予聊天应用在本地机器上编写、构建和运行代码的能力，提供完全交互式的 Shell 体验。

⚠️ 安全警告：此工具提供对本地 Shell 和文件的无过滤访问权限。它不会限制 AI 执行任意命令或进行意外更改。若 AI 产生幻觉或被恶意利用，可能导致危险操作。请仅在您完全理解并接受相关风险的前提下使用。

环境准备

系统要求

• macOS / Linux: 原生支持
• Windows: 仅支持通过 WSL (Windows Subsystem for Linux) 运行
• Python: 推荐 Python 3.12+ (由 uv 自动管理)

前置依赖

需要安装 uv 包管理器。

macOS / Linux (推荐使用 Homebrew):

brew install uv

注意：请确保 uv 安装在全局路径（如 /usr/bin/），否则后续配置可能失败。

Windows (WSL): 请在 WSL 环境中参考官方文档安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装步骤

1. 配置 Claude Desktop

找到并编辑 Claude 的配置文件 claude_desktop_config.json。

macOS / Linux

文件路径：~/Library/Application Support/Claude/claude_desktop_config.json

添加以下内容：

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

可选：指定 Shell 如需强制使用特定 Shell（如 bash 或 zsh）：

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": ["wcgw@latest", "--shell", "/bin/bash"]
    }
  }
}

Windows (WSL)

文件路径：%APPDATA%\Claude\claude_desktop_config.json

首先查找 uv 在 WSL 中的绝对路径：

wsl whereis uv
# 示例输出：uv: /home/user/.local/bin/uv

使用找到的绝对路径更新配置文件：

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

请将 /home/user/.local/bin/uv 替换为您实际的 uv 路径。

2. 重启应用

保存配置文件后，完全退出并重新启动 Claude Desktop 应用。

3. 验证安装

启动成功后，在 Claude 输入框附近应能看到一个 🚀 图标，表示 MCP 服务已就绪。

基本使用

配置完成后，您可以直接在 Claude 对话中下达指令，wcgw 将自动处理本地操作。

核心功能示例

1. 执行 Shell 命令与迭代修复 让 AI 运行命令并自动修复错误：

"请运行编译器检查，如果有错误请自动修复，直到所有测试通过。"

2. 文件读写与编辑 AI 会自动读取项目结构（尊重 .gitignore），并在编辑前读取文件内容以防误覆盖。

"读取 src/main.py，将其中的日志级别改为 DEBUG，并保存。"

3. 交互式终端操作 支持需要交互的命令（如输入密码、使用方向键）。

"运行 npm init 并按提示完成初始化。"

进阶模式 (Modes)

您可以通过自然语言切换 AI 的工作模式：

模式	用途	指令示例
Architect	仅只读，用于分析项目结构和制定计划，禁止修改文件。	"请使用 'architect' 模式分析这个项目。"
Code-writer	限制编辑范围，仅允许修改指定路径或运行特定命令。	"进入 'code-writer' 模式，只允许修改 'tests/**' 目录。"
wcgw	默认模式，拥有完全权限（无限制）。	"使用默认的 wcgw 模式。"

附加到终端 (Attach to Terminal)

您可以实时查看或干预 AI 正在操作的终端会话。

方法 A：使用 VS Code 插件 (推荐) 安装 wcgw VS Code Extension，当工作区路径匹配时，它会自动附加到 AI 的终端。

方法 B：使用 Screen 命令 如果系统安装了 screen，wcgw 会自动在其上运行。

1. 列出会话：

   screen -ls
   

2. 附加到会话（替换为您的实际会话名）：

   screen -x 93358.wcgw.235521
   

3. 安全分离：按下 Ctrl+a 然后按 d 即可分离会话，切勿直接使用 exit 或 Ctrl+d 关闭，以免终止 AI 进程。

任务断点与上下文保存

使用 "ContextSave" 工具可以将当前任务状态、文件内容和描述保存到单个文件中。

• 保存：在对话中点击 "Attach from MCP" 并选择 "KnowledgeTransfer" prompt。
• 恢复：在新对话中输入 "Resume <task_id>"，AI 将加载之前的上下文继续工作。