命令行 MCP 服务器

一个远程 Model Context Protocol 服务器，暴露一个 单一工具 run_command，允许 Claude（通过 Claude Desktop 的 Connectors 功能） 在运行此服务器的机器上执行 shell 命令。

该服务器实现了 OAuth 2.1（动态客户端注册 + PKCE），因为 Claude Desktop 连接器要求进行 OAuth 握手——没有认证服务器的连接器在登录时会被拒绝。 此服务器自动批准授权（无用户提示），这对于个人、隧道暴露的服务器来说是可以的。

⚠️ 安全警告：任何能够访问此服务器并完成（自动）OAuth 流程的人都可以以运行该服务器的用户身份执行任意命令。只能通过私有隧道（cloudflared / ngrok）暴露它，切勿在公共网络上暴露。

工作原理

• 传输方式：Streamable HTTP（Claude Desktop 连接器要求的传输方式）。

• 无状态：每个请求都会启动一个全新的服务器/传输实例（无需会话存储）。

• 端点：POST /mcp

• 健康检查：GET /health

工具

run_command

执行 shell 命令。在 Windows 上，默认 shell 是 cmd.exe（使用 dir、cd，而不是 ls/pwd），除非你传入 shell: "powershell"。

get_info

返回操作系统、架构、默认 shell（Windows 上为 cmd.exe）以及当前工作目录——调用一次，以便客户端知道使用哪个 shell。

read_file

读取文本文件（可选的 offset/limit 行范围）。path 是绝对路径或相对于 cwd 的路径。

list_files

列出目录内容。recursive: true 会遍历目录树（深度限制为 4）。

edit_file

精确字符串替换——编辑代码的首选方式（无需 shell 转义）。 path、old_text、new_text，可选 replace_all。除非设置了 replace_all，否则 old_text 必须是唯一的。返回简短的 diff。

apply_patch

通过 git apply 应用统一 diff（带有 --3way 回退）。cwd = 仓库根目录，patch = diff 文本。

write_file

将完整内容写入文件（overwrite 或 append）。

batch_read

一次调用读取多个文件。files：{ path, offset?, limit? } 数组。

batch_edit

一次调用在一个或多个文件中应用多个精确文本编辑。事务性：在写入任何文件之前验证每个 old_text，因此缺失/模糊的匹配会中止整个批次（不更改任何内容）。每个编辑：{ path, old_text, new_text, replace_all? }。

原生 git 透传

git_status（-sb）、git_diff（staged + paths 选项）、git_log（max_count、revision）、git_show（revision）。每个都接受可选的 cwd。

所有文件路径都在运行服务器的宿主机上解析——它们指向这台机器，而不是 Claude 的沙箱。

本地运行

npm install
npm start
# server listens on http://localhost:3000/mcp

可选环境变量：PORT、CMD_TIMEOUT_MS、CMD_MAX_BUFFER。

npm start 运行 start.js，它会在启动服务器之前释放端口 3000（终止占用该端口的任何进程），因此你永远不会遇到 EADDRINUSE。

将其暴露给 Claude Desktop

选项 A — Cloudflare Worker（稳定 URL，无需 trycloudflare，无需域名）

一个本地小代理保持与 Cloudflare Worker 的 WebSocket 连接，该 Worker 成为 你的稳定公共 *.workers.dev MCP 端点。Worker 仅在代理（使用 PROXY_SECRET 认证）连接时 才将流量中继到你的机器。

1. wrangler login（免费 Cloudflare 账户）。

2. 部署：wrangler deploy → 记下你的 URL，例如 https://command-line-mcp.<subdomain>.workers.dev。

3. 设置密钥（与已 gitignore 的 .dev.vars 中的值相同）： wrangler secret put PROXY_SECRET（粘贴 .dev.vars 中的 PROXY_SECRET）。

4. 将代理指向已部署的 Worker：在 .dev.vars 中将 WORKER_URL 设置为该 URL。

5. 在你的机器上，同时运行：

   npm start          # the MCP server on :3000
   npm run agent      # connects to the Worker with the secret

6. 在 Claude Desktop 中：Customize → Connectors → Add custom connector，粘贴 https://command-line-mcp.<subdomain>.workers.dev/mcp。

无需部署的本地测试：wrangler dev --port 8787（Worker 在 :8787 上）， 然后运行 npm run agent——代理从 .dev.vars 读取 WORKER_URL。

选项 B — cloudflared / ngrok 隧道（临时 URL）

Claude Desktop 连接器需要 HTTPS URL，因此在本地运行服务器并通过隧道暴露：

cloudflared tunnel --url http://localhost:3000 --protocol http2
# or: ngrok http 3000

复制生成的 https://… URL 并附加 /mcp，例如 https://abc-123.trycloudflare.com/mcp。

添加到 Claude Desktop

1. 打开 Customize → Connectors → Add custom connector。

2. 粘贴 URL（带 /mcp），例如选项 A 中的 Worker URL。

3. 将其命名为 Command-Line。

4. 保存。Claude 发现 OAuth 元数据，注册客户端，并打开浏览器访问 （自动批准的）授权端点，然后重定向回来并准备就绪。无需手动输入 "OAuth Client ID"——DCR 会处理。

无需 Claude 进行测试

使用 MCP Inspector：

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:3000/mcp

加固（用于非个人用途）

OAuth 已经实现（参见 oauthProvider.js）。对于个人隧道之外的任何用途， 你应该：

1. 将自动批准的 authorize() 替换为真正的同意界面，或至少是 允许列表中的重定向 URI / 客户端集合。

2. 持久化客户端/令牌（目前存储在内存中——重启后会重置）。

3. 托管在稳定的 HTTPS 域名后面（例如 VPS、Cloudflare Workers、Fly.io）。

4. 考虑使用允许的命令列表来限制爆炸半径。

许可证

MIT