Local Computer Agent MCP

中文 | English

把本机文件、命令行和持久终端通过私人 MCP 连接提供给 ChatGPT Chat，让 Chat 能直接读取代码、修改文件、运行命令、查看结果并继续工作。

面向 Windows 10 1809+ / Windows 11。默认使用 Windows PowerShell 5.1（powershell.exe），可选择 PowerShell 7 和 Git Bash。复用官方 MCP SDK、官方 filesystem server 和 Microsoft node-pty，增加独立会话 worker 与 Cloudflare Access OAuth 接入。项目采用 MIT License。

想让 agent 帮你配置？复制 中文一键配置提示词 给能够操作本机的 coding agent。它会检查环境、收集域名/邮箱、完成部署与验证，最后集中交给你完成浏览器授权。“一键”表示一个任务入口，不承诺绕过 Cloudflare 开户、域名准备或本人登录。

能做什么

没有鼠标、键盘或截图控制。MCP 提供执行工具；后台任务结束不会主动唤醒 Chat 开始新的推理轮次。

Related MCP server: Unlimited Agent

完整方案

flowchart LR
  Chat[ChatGPT Chat] --> Access[Cloudflare Access / Managed OAuth]
  Access --> Tunnel[专用 Cloudflare Tunnel]
  Tunnel --> Gateway[本机 Streamable HTTP MCP /mcp]
  Gateway --> Files[官方 filesystem server]
  Gateway --> Worker[每个会话的独立后台 worker]
  Worker --> Shell[PowerShell 5.1 / 7 / Git Bash]
  Worker --> Logs[本机状态与分段输出日志]
  Login[Windows 用户登录] --> Supervisor[隐藏后台管理器]
  Supervisor --> Gateway
  Supervisor --> Tunnel

Cloudflare 提供公网 HTTPS 和用户 OAuth；真正执行命令的是你的 Windows 用户进程。网关监听 loopback，并验证 Access JWT 的签名、issuer、audience、有效期和允许邮箱。每个终端的 worker 单独运行，网关根据会话 ID 重连，而不是把 shell 生命周期绑定到 Chat 的一次 HTTP 请求。

安装前准备

1. 准备 Windows、Node.js 22 或 24、Git for Windows、cloudflared。PowerShell 5.1 随 Windows 提供；配置脚本需要 PowerShell 7，它不改变默认工具 shell。完整集成测试需要这三种 shell。

2. 有一个由 Cloudflare DNS 管理的域名/zone，并选一个未被其他服务使用的子域名，例如 agent.example.com。不要直接使用本文示例域名。

3. 在 Cloudflare Zero Trust 中完成组织初始化，得到 your-team.cloudflareaccess.com 团队域名，并配置 One-time PIN 邮箱登录或已有身份提供方。脚本检查这些前提，不会代你购买域名、选择付费套餐或修改已有组织。

4. 你的 ChatGPT 账户当前界面支持私人远程 MCP / 自定义 app。先检查是否有相应创建入口；产品套餐和客户端支持以当前账户为准。

官方资料：cloudflared 下载、Tunnel 入门、邮箱 PIN 登录、ChatGPT 接入。本项目不需要模型 API key；域名和账户可能有各自费用，部署脚本不创建付费云计算资源。

访问范围

本方案允许被授权的 Chat 使用当前 Windows 用户的文件与命令权限。默认文件 roots 是本机可访问的盘符；任意 shell 不受这些 roots 限制。不要把文件目录白名单理解为命令沙箱。建议用普通用户运行；项目不会自动提升到管理员。

从零配置

以下命令在 PowerShell 7 中执行。将邮箱与域名替换成你自己的值。

1. 获取代码与依赖

git clone https://github.com/AblazeGHR/chat-local-agent-mcp.git
cd chat-local-agent-mcp
npm ci
node scripts/detect-windows.mjs
npm test

测试无需 Cloudflare token、真实域名或 config.local.json。它使用独立端口/测试目录，调用真实文件 MCP、Windows shell 和 ConPTY。非 Windows 环境只运行可移植的认证测试，不代表 Windows 功能已验收。

2. 准备 Cloudflare API token

创建一个只作用于目标账户和 zone 的自定义 token，赋予：

权限名称和组合选项参见 Cloudflare 权限表。脚本会读取 zone、Access 应用/策略、组织、身份提供方、tunnel、DNS，并创建专用应用、策略、tunnel、DNS。无需全局 API key 或全账户管理员 token。

用遮蔽输入设置用户环境变量；不要把 token 粘贴进 Chat、源码或命令历史：

$secureToken = Read-Host 'Cloudflare API token' -AsSecureString
$plainToken = [System.Net.NetworkCredential]::new('', $secureToken).Password
[Environment]::SetEnvironmentVariable('CLOUDFLARE_API_TOKEN', $plainToken, 'User')
Remove-Variable plainToken, secureToken

脚本读取当前进程环境，缺失时读取用户环境。Token 只用于部署，不是 ChatGPT 的登录令牌；配置完成后若不再管理云端资源，可以移除或撤销它，已有 tunnel 运行使用独立凭据。

3. 检查并创建云端资源

# 只读检查，不创建云端资源、不写入运行配置
./scripts/provision-cloudflare.ps1 -Hostname agent.example.com -AllowedEmails you@example.com

# 正式创建/复用本 checkout 拥有的资源
./scripts/provision-cloudflare.ps1 -Hostname agent.example.com -AllowedEmails you@example.com -Apply

脚本先建立仅允许指定邮箱的 Access 应用与 Managed OAuth，再建立专用本地管理 tunnel 和代理 CNAME。默认 MCP/control 端口为 9752/9753；被占用时选择其他相邻端口，例如加 -Port 9852。新部署的 tunnel 名由 hostname 派生。

已有简单 email-only Access 策略时，可以用 -ExistingAppName 'Your existing app' 替代 -AllowedEmails，复制允许邮箱；不依赖 Pan，不修改来源应用。

生成的本机文件：

重复执行同一参数会识别并复用本 checkout 的资源，保留本地运行偏好。若资源属于别的应用、身份策略变化或本机配置不同，脚本拒绝自动覆盖。丢失所有权记录/凭据时不要强行接管；先核对 Cloudflare 资源。多个独立部署请使用独立 clone 与子域名。

脚本目前读取前 50 个可访问 zone、前 100 个 Access 应用与 tunnel；个人账户通常足够，较大账户需扩展分页后使用。中途失败可能留下已创建资源，记录在 runtime/cloudflare-resources.json；先检查记录和云端状态再重试。

4. 启动与登录自启

npm run service:start
npm run status
./scripts/install-autostart.ps1

管理器、网关与 tunnel 隐藏后台运行，关闭启动终端不会停止它们。当前用户 Startup 目录的 ChatLocalAgentMCP.vbs 在用户登录后启动管理器；这不是未登录时的系统级开机服务。管理器在子进程退出后等待 3 秒重新启动。

5. 在 ChatGPT 创建私人连接

1. 在 ChatGPT 网页端找到自定义 app/MCP 创建入口，按账户界面要求启用 Developer mode。

2. 名称填 Local Computer Agent，URL 填 https://agent.example.com/mcp，认证选 OAuth。完整 URL 必须包含 /mcp。

3. 完成本人邮箱/身份提供方登录与授权。支持动态客户端注册的流程不需要手工 Client ID/Secret；不要填 Cloudflare API token。

4. 创建新 Chat 并选中连接，发送：

   调用 computer_info，然后用默认 shell 执行 $PSVersionTable.PSVersion.ToString() 和 Write-Output 'MCP 中文验收成功'，报告真实输出与退出码。再后台执行 Start-Sleep -Seconds 5; Write-Output '后台完成'; exit 7，用会话 ID 读至结束并报告退出码。

网页接入完成后再核对桌面客户端是否能选择连接。看到连接名称不等于工具已发现；本人授权、tools/list 和实际调用才是客户端证据。

Cloudflare 配置细节与手工核对

方案使用命名的本地管理 tunnel，不运行 quick tunnel，也不复用其他服务的 tunnel。runtime/tunnel.yml 指向 127.0.0.1:9752，不会开放本机 LAN 端口。公网 hostname 有独立 Access 应用、email Allow 策略和 AUD。

Managed OAuth 配置启用 DCR，允许 ChatGPT 回调：

https://chatgpt.com/connector_platform_oauth_redirect
https://chatgpt.com/connector/oauth/*

还允许 localhost/loopback 客户端；Access token lifetime 为 15 分钟，grant session 为 24 小时。回调和产品支持会变化，出错时核对 当前 Managed OAuth 文档 与实际客户端请求，不直接放开所有回调或删除认证。

客户拿到的是 OAuth token；Cloudflare 校验后向 origin 注入签名 Cf-Access-Jwt-Assertion。网关验证该 JWT 的 RS256、公钥、issuer、AUD、expiry、subject 与邮箱。仅存在 header 不算身份通过。

工具与使用

共 19 个工具：

文件工具使用绝对路径。search_files 搜索文件名；内容搜索用 shell 的 rg 或 Select-String。edit 的 oldText 必须精确匹配，默认预期 1 次；匹配不唯一时不写入。

{"command":"Write-Output '你好'; exit 0","shell":"powershell","mode":"wait","waitMs":1000}

shell 可选 powershell（5.1）、powershell7、git-bash。waitMs 最多 20 秒；超时返回 running 和会话 ID，不终止进程。显式用 exit N 设定退出码；PowerShell 原生程序若需传播其状态，使用 exit $LASTEXITCODE。

{"command":"Start-Sleep -Seconds 10; Write-Output '完成'; exit 7","mode":"detach","requestId":"task-001"}

detach 立即返回 ID，随后用 session_read 获取结果。重试相同启动请求时复用 requestId；不同请求复用同一 ID 会被拒绝，省略 ID 则每次新建进程。

保留变量、cwd、Read-Host、SSH 或 REPL 时，使用 terminal_start → session_write → session_read。输入默认 newline=true；原始键输入设为 false。PTY 有 ANSI 控制符、回显和提示符，安静不代表命令完成；PTY 的 exitCode 是整个终端的退出码，单命令验收宜用 shell。更多约定见 CHAT_INSTRUCTIONS.md。

生命周期、管理与卸载

session_read 的 offset/nextOffset 是 UTF-8 字节游标。每次下一页使用返回的 nextOffset。默认每会话保留最近约 64 MiB；旧段淘汰后返回 baseOffset/outputEvicted。默认一页 64 KiB，最多 256 KiB。无法联系 worker 时报告 unreachable，不伪报完成、不猜测 PID 并终止它。

默认最多 32 个可联系的活跃会话。完成记录、测试夹具和服务日志不自动清理；关闭闲置终端，确认历史会话结束后手工归档。代码更新后旧 worker 使用创建时版本，worker 更新需新建会话。

npm run status
npm run service:start
npm run service:stop
npm run service:restart
node src/manage.mjs restart-gateway
./scripts/install-autostart.ps1 -Remove

最后一条仅移除自启，不停止服务。要卸载：先关闭所需会话，移除自启并停止服务，再根据所有权记录手工删除专用 Cloudflare 应用、DNS 和 tunnel。不要删除其他服务的资源。移动安装目录前先移除旧自启入口，之后在新目录重新安装。前台调试 npm start 前先停止管理器，避免端口竞争。

验证与排错

npm test
# 部署后的完整生命周期检查：会短暂停止/重启本项目服务，需要已安装自启
node scripts/verify-live.mjs

集成测试覆盖文件编辑、三种 shell 中文与退出码、交互输入、输出轮转、启动去重、网关死亡后恢复、Ctrl+C 与关闭进程树。verify-live.mjs 额外检查管理器停止/启动、实际 VBS 自启入口、watchdog 和公网 OAuth 发现；使用本机管理令牌，不代表 ChatGPT 本人 OAuth 已通过。它写入忽略的 runtime/live-acceptance.json。

运行状态 npm run status 不等于公网或 Chat 可用，逐层核验。没有进行 Windows 注销/重启测试时，不把执行 VBS 的证明称为真实重启证明。

开源与隐私

config.local.json、runtime/、.env、node_modules 不入 Git。runtime ACL 限制到当前用户、SYSTEM 与 Administrators。审计只记录工具名/时间/耗时/失败标志，命令本身与输出可能保存在会话目录。发布前检查暂存内容；不要把日志、真实域名/邮箱、token 或 tunnel secret 放入 issues。详见 SECURITY.md。

项目选型与源码调查见 RESEARCH.md。欢迎提交带复现步骤的 issue/PR；说明 Windows、Node、shell 版本与脱敏日志。GitHub Actions 在 Windows 上运行 Node 22/24 测试，不使用个人 Cloudflare 凭据。