Chat2Local

简体中文 · English

让 ChatGPT 通过 MCP 访问并操作你授权的本地电脑和项目。

Chat2Local 是一个面向单用户、自托管场景的轻量 MCP Agent。它可以读取和修改本地文件、运行命令、管理长时间运行的进程，并通过 Hub + Agent 模式连接多台电脑或服务器。

项目同时提供 Core / CLI 和 Windows Desktop：前者适合开发者、服务器和命令行环境，后者在同一套 Core 外提供图形化管理、系统托盘、日志和 portable EXE。

Features

你可以直接在 ChatGPT 中让它：

• 阅读和搜索本地项目代码，而不需要反复上传文件
• 修改文件、应用 patch，并继续检查修改结果
• 运行测试、构建、脚本或其他 Shell 命令
• 查看长时间运行进程的输出，并继续与进程交互
• 在多台电脑或服务器之间选择目标设备执行操作
• 通过 Handoff 保存项目工作线或个人研究、计划和想法，让新的 Chat 继续之前的上下文
• 通过可选 Chrome 扩展读取和操作网页，支持 DOM 探查、点击、输入和滚动

Chat2Local 主要围绕 ChatGPT + MCP 的实际工作流开发和测试。其他支持 MCP 的客户端也可以连接，但目前不是主要测试目标。

架构

单设备时，ChatGPT 直接连接 Chat2Local：

ChatGPT
   │ MCP / HTTPS
   ▼
Chat2Local
   │
   └── Local workspace / processes

多设备时，由 Hub 提供统一 MCP endpoint，各 Agent 主动连接 Hub：

                    ┌── Hub local workspace
                    │
ChatGPT ── MCP ──▶ Hub
                    │
                    ├── Agent: Windows PC
                    ├── Agent: Server
                    └── Agent: Other device

Agent 不对 ChatGPT 暴露 MCP endpoint，也不需要对公网开放入站端口；它只需要能够主动连接 Hub。

安装

Windows Desktop

Windows 用户可以从 GitHub Releases 下载：

Chat2Local-v<version>-windows-x64.zip

解压后直接运行：

Chat2Local.exe

portable 版本已经包含 Python runtime、Core 和 Desktop GUI，不要求系统预先安装 Python。

Core / CLI

Core 要求 Python 3.12+。

独立 Core 在 Windows、Linux、macOS 上均自带本地 Web UI。启动后可在浏览器访问 http://127.0.0.1:8767/（实际地址也会写入日志），管理配置、日志、设备、Token 和自启。 Browser Bridge 固定使用用户配置的端口（默认 8766）。Web UI 未指定端口时从 8767 起最多尝试 10 个端口， 成功后显示实际地址；通过配置或 CLI 显式指定端口时不自动回退。 运行时无需 Node.js；详见本地 Web UI 与跨平台自启。原 Windows ZIP / EXE 使用方式保持不变。

推荐使用 uv tool 安装到独立环境：

uv tool install chat2local
chat2local --help

也可以使用 pip：

python -m pip install chat2local
chat2local --help

快速开始

Standalone

在希望授权给 Chat2Local 的目录中运行：

chat2local

也可以显式指定 workspace：

chat2local --workspace D:\Projects\example

如果不传 --workspace，启动时的当前目录就是默认 workspace。

Hub + Agent

Hub：

$env:CHAT2LOCAL_HUB_TOKEN = '<shared-secret>'
chat2local hub --device-id hub --host 127.0.0.1 --port 8765

Agent：

$env:CHAT2LOCAL_HUB_TOKEN = '<shared-secret>'
chat2local agent --device-id desktop --hub-url wss://hub.example.com/device/ws

Hub 和 Agent 使用同一个 shared token。公网 Agent 应使用 wss://。

上面的 Hub 示例只监听 loopback。只有在已经配置防火墙、TLS 反向代理或其他可信网络边界时， 才应把 Hub 直接监听到 0.0.0.0。CHAT2LOCAL_HUB_TOKEN 只保护 Hub ↔ Agent 的 /device/ws， 不会保护 MCP /mcp endpoint；公网 MCP endpoint 应另外启用 OAuth 或可信的外部访问控制。

连接到 ChatGPT

ChatGPT Web 不能直接访问 localhost 上的 MCP Server，因此需要为 Chat2Local 提供一条 ChatGPT 可以使用的连接路径。

OpenAI Secure MCP Tunnel

对于个人使用、本地开发或不希望把 MCP Server 暴露到公网的场景，可以使用 OpenAI 官方的 Secure MCP Tunnel。

tunnel-client 运行在能够访问 Chat2Local 的机器或网络中，并主动通过 HTTPS 连接 OpenAI。这样 Chat2Local 本身不需要开放公网入站端口，也不需要拥有公开 HTTPS 地址。

典型结构：

ChatGPT
   │
   │ OpenAI Secure MCP Tunnel
   ▼
tunnel-client
   │
   ▼
Chat2Local /mcp

在 ChatGPT 中创建自定义 MCP Server / Plugin 时，Connection 选择 Tunnel，再选择或填写对应的 tunnel_id 即可。

Standalone 模式下，tunnel-client 可以直接运行在本机；Hub + Agent 模式下，可以把它运行在 Hub 所在机器或其他能够访问 Hub MCP endpoint 的环境中。

Secure MCP Tunnel 适合私有连接和开发测试；如果准备公开发布 Plugin，则仍需要稳定、可公网访问的 HTTPS MCP endpoint。

公网 HTTPS endpoint

另一种方式是通过反向代理、隧道服务或自己的域名，把 Chat2Local 的 MCP endpoint 暴露为公网 HTTPS 地址，例如：

https://mcp.example.com/mcp

然后在 ChatGPT 中创建自定义 MCP Server / Plugin，并填写该 Server URL。公网部署建议启用 HTTPS，并配置 OAuth 或其他可信的访问控制。

连接成功后，可以先让 ChatGPT 读取当前 workspace，或者调用 list_devices 验证 Chat2Local 是否已经正常连接。

MCP Tools

Chat2Local 当前公开 12 个 MCP tools，覆盖文件读取与搜索、patch 修改、Shell / Process 操作、多设备选择、Handoff 和可选扩展能力。

capability_discover 默认以 summary 查询指定设备的能力概览和实时可用状态；选中能力后用 detail: "full" 查询参数 JSON Schema、结果契约和恢复指导，再通过 capability_execute 执行。 浏览器提供 16 个内部能力，包括标签页创建/查询/选择、网页读取/定位，以及点击/填写、双击/悬停/聚焦、原生选择/勾选、滚动、合成按键和状态等待。 这些能力均通过按网站授权的可选 Chrome 扩展执行，默认不启动浏览器监听；扩展未连接不会影响原有工具。 Chrome 扩展 ZIP 可从 GitHub Releases 下载；安装与配对见 浏览器扩展说明。

当前公开的 Tool：

read · search · apply_patch · exec_command · interact_process
kill_process · list_devices · handoff_list · handoff_get · handoff_save

远程调用可以通过 device 指定目标设备；省略时使用当前 MCP Server 所在设备。

三个 Handoff Tool 均接受可选的 scope：默认 "workspace" 按项目工作区保存，兼容旧调用； 没有具体项目归属的研究、计划或初步想法使用 "personal"，无需 Workspace，也不能显式传入 workspace（包括 null）。两种作用域允许相同的 Workstream ID，记录彼此独立。

记录均使用 Markdown，保存在选定设备的用户数据目录中：Workspace 使用 ~/.chat2local/handoffs/<workspace-key>/，Personal 使用 ~/.chat2local/handoffs/_personal/。 现有文件无需迁移，各设备之间不自动同步。先用 handoff_list 查看标题和摘要，再按需 handoff_get 读取正文；handoff_save 用 expected_revision=0 新建，更新使用最新 revision。

配置

默认配置文件：

~/.chat2local/config.yaml

完整示例见 config.example.yaml。

一个最小的 Hub / Agent 配置示例：

hub:
  device_id: hub
  host: 127.0.0.1
  port: 8765
  token_file: ~/.chat2local/hub.token

agent:
  device_id: desktop
  hub_url: wss://hub.example.com/device/ws
  token_file: ~/.chat2local/hub.token
  proxy: system

security.allowed_roots 用来限制本机可选择的 workspace 范围。默认值 [] 不代表开放整个文件系统，而是只授权启动时的默认 workspace。

CLI 参数只覆盖当前启动，不会自动写回 config.yaml。Windows Desktop 的 Settings 可以编辑持久化配置。

进阶配置

Chat2Local 还支持：

• Agent → Hub 使用系统代理、直连或显式 HTTP / HTTPS / SOCKS4 / SOCKS5 代理
• Standalone / Hub MCP HTTP endpoint 启用 OAuth Resource Server 模式
• 当前 OAuth provider 支持 WorkOS AuthKit

Core / CLI 使用 SOCKS 时需要额外安装 python-socks[asyncio]；Windows Desktop portable 已内置该依赖。

安全模型

Chat2Local 提供明确的应用级访问边界，但它不是 OS sandbox。

• 文件工具始终限制在当前 workspace 内
• workspace 必须位于本机允许的 security.allowed_roots 内
• 阻止通过 ..、workspace 外绝对路径、symlink / junction 逃逸
• exec_command 仍拥有 Chat2Local 当前 OS 用户的权限
• Agent shared token 只保护 Hub ↔ Agent 连接
• 公网 MCP endpoint 应使用 HTTPS，并配置 OAuth 或可信的外部访问控制
• 日志不会记录 token、完整认证 payload 或 Tool 参数内容

如果需要更强隔离，应配合独立 OS 用户、容器、虚拟机或其他系统级机制使用。

Windows Desktop

Desktop GUI 当前提供：

• Core 状态和 Standalone / Hub / Agent 启停
• workspace 选择
• Hub 在线设备列表
• config.yaml 设置编辑
• Core 日志查看
• Windows 系统托盘
• 登录启动与静默启动
• Core 自动启动
• 简体中文 / English
• single-instance

关闭窗口默认隐藏到系统托盘；退出 Desktop 不会自动停止正在运行的 Core。

Desktop 的开发与打包说明见 gui/pywebview/README.md。

从源码运行与构建

如果你希望直接从仓库运行、测试或修改 Chat2Local，克隆仓库后：

uv sync
uv run pytest

构建 Windows portable：

uv sync --group pywebview-gui --group desktop-build
uv run --group pywebview-gui --group desktop-build python scripts/build_windows.py

输出目录：

dist/windows/Chat2Local/

License

Chat2Local 使用 MIT License。