# Local Tunnel MCP

简体中文 | [English](README.en.md)

让服务器上的 AI Agent 直接操作你的本地电脑：读写代码、搜索文件、执行命令。

把所有电脑都接入同一台服务器，它就成了你的控制中心：在一个 AI 会话里，同时处理不同电脑上的不同项目。

## 适合这些场景

- **AI 在服务器，代码在本地：** Claude Code、Codex 跑在服务器上长期在线，代码和开发环境留在自己电脑上，不用同步。
- **多台电脑统一管理：** 公司电脑、家里电脑和 Mac 都连上同一台服务器，一句话就能指定在哪台上干活。
- **跨机器协作：** 对比两台电脑上的配置，把一台的改动同步到另一台，在 Windows 上构建、在 Mac 上验证。
- **用手机也能干活：** 只要能连上服务器，就能让 AI 在你家里的电脑上改代码、跑测试。
- **让 AI 看本地内容：** 日志、文档、截图，不用复制粘贴，直接告诉它在哪。

## 安装

从 [Releases](https://github.com/PLZY/local-tunnel-mcp/releases/latest) 下载对应系统的安装包，运行环境已经打包在内，不用再装 Node.js。

安装包没有购买代码签名，所以系统会弹出安全提示，按下面的步骤放行即可。

### Windows

1. 下载 `LocalTunnel-Setup-x.x.x.exe` 并双击。
2. 如果出现“Windows 已保护你的电脑”，点击「更多信息」，再点击「仍要运行」。
3. 完成安装后，从开始菜单打开 Local Tunnel。
4. 安装 PowerShell 7，AI 执行命令时需要用到：

   ```powershell
   winget install --id Microsoft.PowerShell
   ```

### macOS

1. 下载对应芯片的安装包：Apple 芯片选 `LocalTunnel-x.x.x-arm64.dmg`，Intel 芯片选 `LocalTunnel-x.x.x-x64.dmg`。
2. 打开 dmg，把 LocalTunnel 拖到 Applications 文件夹。
3. 打开“终端”，执行下面的命令：

   ```bash
   xattr -cr /Applications/LocalTunnel.app
   ```

4. 从“应用程序”文件夹打开 LocalTunnel。

如果没有执行第 3 步，macOS 可能提示“已损坏，无法打开”或“无法验证开发者”。这不是文件真的损坏，而是系统拦截了未签名的应用，执行第 3 步后就能正常打开。

## 怎么用

**1. 连接服务器**

打开应用后，浏览器会显示控制台。填写服务器地址、登录方式和允许 AI 访问的目录，然后打开「开启远程访问」。首次连接时确认信任服务器即可。

**2. 接入 AI**

点击「复制 MCP 配置」，把配置添加到服务器上的 AI 工具里。

**3. 直接说需求**

> 把 home-mac 上的这个 bug 修了，跑一遍测试
>
> 看看 windows-pc 下载目录里最新的截图

有多台电脑时，每台都重复上面的步骤，并分配不同的服务器转发端口。

想让 AI 用得更顺手，可以把[本机文件访问提示词.md](本机文件访问提示词.md)里的提示词加入服务器项目的 `CLAUDE.md` 或 `AGENTS.md`。

**退出**

关闭浏览器页面不会断开连接，AI 仍然可以访问你的电脑。

- **Windows：** 右键任务栏右下角的托盘图标，选择「退出」。
- **macOS：** 右键 Dock 图标，选择「退出」，或按 `Cmd+Q`。

## 功能

- **文件：** 浏览目录，读取、编辑、新建文件，大文件也不卡。
- **搜索：** 按文件名或内容搜索，支持正则。
- **命令：** 在本地执行构建、测试、git 等命令。
- **图片：** 让 AI 直接查看本地截图和图片。
- **多设备：** 一台服务器连多台电脑，一台电脑也能连多台服务器，操作前核对目标设备。
- **连接管理：** 网页控制台统一配置，支持密钥和密码登录，断线自动重连。
- **无需改造服务器：** 不用在服务器上部署程序，也不用开放新的公网端口。

## 安全提示

开启后，AI 能以你的用户身份操作这台电脑。只连接你信任的服务器，保管好连接配置里的 Token，也不要把转发端口开放到公网。

## 开发

需要 Node.js 22 或更新版本。

```bash
npm ci
npm test
npm start
```

## 许可证

本项目仅供学习和交流使用，**禁止用于商业目的**。详见 [LICENSE](LICENSE)。