Local Commander

---

问题所在

你的 AI 能编写代码，却看不到你的项目。你把文件复制到聊天中，再把测试输出粘贴回来，每条命令都得自己运行。给它一个原始终端虽能解决这个问题，但它也就能访问所有内容。

Local Commander 介于两者之间。你的 AI 可以在你的电脑上使用真正的工具完成实际工作，但仅限于你选定的文件夹和你允许的命令。你可以继续使用已经打开的聊天窗口。

大家用它做什么

代码	运行测试和构建 · 修复实际代码库中的错误 · 推送前检查差异
本地服务	启动开发服务器 · 检查服务是否运行 · 查看日志
项目上下文	通过一次提问获取状态、近期提交和脚本 · 搜索代码库 · 就地编辑文件

试着这样提问：

“在 my-app 中运行测试，并告诉我哪些测试失败了。”
“启动开发服务器，并检查端口 3000 是否有响应。”
“显示自昨天以来代码库中的变更。”

为什么选择 Local Commander

🔒 访问权限由你决定。 你的 AI 只能看到你选定的文件夹。默认会屏蔽 .env 和私钥等机密文件。

🧰 真正的工具，而非原始 Shell。 命令只能从允许列表中选择（Git、Node、npm、Python 等），参数也彼此独立。没有可供注入的自由格式 Shell 字符串。

⚡ 并行工作，互不冲突。 独立命令可以并行运行。开发服务器等长时间运行的进程会持续运行，同时你的 AI 可以检查其输出。

🏠 始终在你的电脑上运行。 服务在本地运行，只与启动它的 AI 客户端通信。无需账户、无遥测，除非你主动启用，否则审计日志处于关闭状态。

🔌 兼容你已有的 AI。 Claude Desktop、Claude Code、Cursor、Codex、通过隧道连接的 ChatGPT，或任何支持 MCP 的客户端。

快速开始

选择适合你的方式。每种方式只需几分钟。

你使用的工具	操作
Claude Desktop	从最新版本下载 .mcpb 文件并打开。选择你的文件夹。无需 Node.js。
Claude Desktop 或 Cursor，且已安装 Node.js 20+	运行 npx -y local-commander-mcp-agent setup --root /path/to/your/projects --client all，然后重启应用。
Claude Code	运行 claude mcp add local-commander -- npx -y local-commander-mcp-agent --stdio /path/to/your/projects
Docker	将你的项目挂载到 ghcr.io/netbka/local-commander-mcp-agent。参见 Docker。
其他 MCP 客户端	运行 npx -y local-commander-mcp-agent --stdio /path/to/your/projects。参见 npx。

安装前须知

我的 AI 可以访问哪些内容？

只能访问你选择的文件夹，并且只能通过 Local Commander 的工具访问：读取和编辑文件、检查 Git、运行允许列表中的命令、开发进程，以及向 localhost 发送请求。你可以在配置文件中更改命令列表。

它是沙盒吗？

不是。文件工具仅限于你的文件夹，但像 node 或 python 这样的允许程序会以你的账户权限运行，也能读取你可以读取的内容。如需严格隔离，请使用 Docker 镜像、单独的低权限账户或虚拟机。

我的数据会被发送到别处吗？

不会。服务在你的计算机上运行，只与启动它的 AI 客户端通信。它不会收集遥测数据。AI 客户端发送给其自身服务提供商的内容，由你和该服务提供商自行处理。

可以卸载它吗？

可以。npx -y local-commander-mcp-agent setup --remove 会将其从 Claude Desktop 和 Cursor 中移除，并保留之前配置的备份。在 Claude Desktop 中，你也可以停用或移除该扩展。

如果有多台计算机或团队，该怎么办？

此开源版本一次只能在一台计算机上运行。托管服务 localcmd.app 可将 ChatGPT、Claude 或你自己的 Agent 同时连接到所有 Windows PC，在多台计算机上并行执行任务，并显示每项任务在哪台计算机上运行。这是一个独立产品，使用此版本不需要它。

---

技术参考

• 工具
• 安装选项：setup · npx · Docker · Node.js · HTTP 和 ChatGPT
• 安全模型
• 配置
• 开发

工具

工具	用途
project_snapshot	一次调用获取仓库上下文：状态、差异统计、近期提交、包脚本、受管理进程
fs_read、fs_list、fs_search	在允许的根目录内进行有范围限制的读取、列举和文本搜索
fs_write、fs_replace	创建或替换文件，或执行精确的定向替换
git_status、git_diff、git_log	简洁地检查 Git
command_run、parallel_command_run	使用独立参数运行一个或多个允许的可执行文件
process_start、process_list、process_output、process_kill	长时间运行的开发进程
scheduler_status	活跃或排队的工作及资源锁
localhost_request	仅向允许的本地主机发送有范围限制的 HTTP 请求

安装选项

一条命令完成设置

要求：Node.js 20+。

npx -y local-commander-mcp-agent setup --root /path/to/your/projects --client all

这会向 Claude Desktop 和／或 Cursor 的 MCP 配置中添加一个 local-commander 条目，并保留之前文件的带时间戳备份。重复使用 --root 可添加更多文件夹，使用 --client claude-desktop 或 --client cursor 可指定一个客户端，使用 --dry-run 可预览，使用 setup --remove 可再次移除该条目。之后请重启客户端。

npx

要求：Node.js 20+。服务可以访问的文件夹由 --stdio 后的参数指定：

{
  "mcpServers": {
    "local-commander": {
      "command": "npx",
      "args": ["-y", "local-commander-mcp-agent", "--stdio", "/path/to/your/projects"]
    }
  }
}

在 Windows 上，有些客户端需要使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", ...]；setup 会为你写入这种格式。

仍可使用 LCMCP_ROOTS 代替文件夹参数。在 stdio 模式下，本地状态保存在 ~/.local-commander-mcp-agent 中，除非设置了 LCMCP_OAUTH_STATE_PATH。

在 Windows 上，多个根目录之间使用 ; 分隔，路径格式如 C:\\Users\\you\\source\\repos。该软件包包含一个小型 Windows 文件读取辅助程序，因此安装时无需编译。

Docker

容器就是沙箱：服务只能看到你挂载到 /workspace 下的文件夹。镜像发布于 ghcr.io/netbka/local-commander-mcp-agent（标签为 latest 和各个版本）。如需自行构建：docker build -t local-commander-mcp-agent .

MCP 客户端配置（Claude Desktop、Cursor、Claude Code、Codex 等）：

{
  "mcpServers": {
    "local-commander": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/projects:/workspace/projects",
        "ghcr.io/netbka/local-commander-mcp-agent"
      ]
    }
  }
}

在 Windows 上，请使用类似 C:\\Users\\you\\source\\repos:/workspace/repos 的路径。镜像包含 Node.js 22、Git 和 Python 3。可通过扩展镜像来添加工具。

使用 HTTP 而非 stdio：

docker run --rm -p 127.0.0.1:17321:17321 \
  -e LCMCP_TOKEN=generate-a-long-random-token \
  -v /path/to/your/projects:/workspace/projects \
  ghcr.io/netbka/local-commander-mcp-agent --http

镜像默认使用 --stdio；镜像名称后面的任何其他参数（此处为 --http）都会替代它并启动 HTTP 服务。端点为 http://127.0.0.1:17321/mcp，并使用 Authorization: Bearer <token>。仅在 127.0.0.1 上发布端口。

Node.js

要求：Node.js 20+。

npm install
npm run build

{
  "mcpServers": {
    "local-commander": {
      "command": "node",
      "args": ["/path/to/local-commander-mcp-agent/dist/index.js", "--stdio", "/path/to/your/projects"]
    }
  }
}

在 stdio 模式下，stdout 仅承载 MCP 消息，日志会写入 stderr。HTTP 身份验证设置不适用，因为只有启动该进程的客户端才能与其通信。

在 Windows 上，构建过程还会使用 Windows 自带的 .NET Framework 编译器编译一个小型文件读取辅助程序（release/personal/OwnerBridge.exe）。其他平台使用 Node 读取器。

HTTP 和 ChatGPT

cp local-commander.config.example.json local-commander.config.json   # set "roots"
LCMCP_AUTH_MODE=oauth LCMCP_PUBLIC_BASE_URL=https://your-tunnel.example.com npm start

客户端启动授权时，系统会在本地终端中打印一次性批准码。本地客户端也可使用 Bearer 模式（LCMCP_AUTH_MODE=bearer、LCMCP_TOKEN=...）。

安全模型

• 直接文件操作受配置的根目录限制；现有路径会通过 realpath 解析，因此符号链接无法逃出根目录。
• 默认会阻止访问常见机密文件（.env、私钥、凭据文件）。
• command_run 接受可执行文件和参数数组，绝不接受 shell 字符串。可执行文件采用允许列表，并且只会从绝对 PATH 目录中解析。
• 命令执行时间和输出均有限制；HTTP 仅限 localhost，且不会跟随重定向。
• Docker 外部的子进程不会受到操作系统沙箱隔离：获准的解释器可以读取当前账户可读取的任何内容。如需严格隔离，请使用 Docker 镜像、单独的低权限账户或虚拟机。

配置

变量	含义
LCMCP_TRANSPORT	使用 stdio 提供服务（与 --stdio 相同）
LCMCP_ROOTS	允许访问的根目录，使用操作系统的路径分隔符分隔（Windows 上为 ;，其他平台上为 :）
LCMCP_CONFIG	配置文件路径（默认为工作目录中的 local-commander.config.json）
LCMCP_HOST、LCMCP_PORT、LCMCP_MCP_PATH	HTTP 绑定地址和路径
LCMCP_AUTH_MODE	仅用于 HTTP：oauth、bearer 或 none
LCMCP_TOKEN	Bearer 模式的令牌
LCMCP_PUBLIC_BASE_URL	用作 OAuth 颁发者/资源的公共 HTTPS 源
LCMCP_OAUTH_STATE_PATH	OAuth 和本地状态文件路径
LCMCP_AUDIT_MODE	off（默认）、minimal、diagnostic 或 full（full 需要 LCMCP_AUDIT_RECOVERY_KEY）

配置文件还可以设置命令允许列表（shell.allowedCommands）、大小限制和 localhost 主机；请参阅 local-commander.config.example.json。

开发

npm run typecheck
npm test
npm run build

---