Skip to main content
Glama
Gemini Terminal Bridge

Gemini Terminal Bridge

by Fangwenky
README.md
# Gemini Terminal Bridge

让 **Gemini Mac 桌面端(任务模式)** 通过 MCP 稳定使用本机完整终端环境(基于 [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP)),无需关闭 Gemini 默认沙盒,也不需要任何辅助功能或屏幕录制权限。

## 解决什么问题

直接在 Gemini 任务模式里挂载本地终端 MCP(如 Desktop Commander)时,会受到 Gemini 任务沙盒的限制:

1. **无法使用 SSH / Git 凭据**:沙盒禁止读取 `~/.ssh/known_hosts` 和私钥,且部分配置会覆盖 `HOME`,导致 `git push`、`ssh`、`gh` 失败。
2. **无法写入系统/工具目录**:`brew install`、`npm install -g` 写入 `/opt/homebrew` 返回 `Operation not permitted`。
3. **长任务断连即中断**:安装或构建耗时较长时,一旦 Gemini 重启或断开 MCP 连接,沙盒内的子进程会一并丢失。

## 架构原理

Gemini 任务模式虽然限制了本地文件与系统权限,但允许沙盒内的 MCP 进程访问 `127.0.0.1`。本项目把服务拆成两半:

```mermaid
flowchart LR
  G["Gemini Mac 桌面端<br/>(任务模式 · 默认沙盒)"] -->|stdio MCP| P["proxy/proxy.mjs<br/>零依赖转发器"]
  P -->|"HTTP 127.0.0.1 + Bearer Token"| H["src/host.mjs<br/>Streamable HTTP 服务(沙盒外)"]
  A["Gemini Terminal Bridge.app<br/>菜单栏 >_ 常驻托管"] -->|启动并守护| H
  H -->|常驻 stdio 子进程| DC["Desktop Commander MCP<br/>加载真实登录 Shell 环境"]
```

- **沙盒内 (`proxy/proxy.mjs`)**:零第三方依赖的 stdio MCP 转发器,不定义任何工具,仅把 JSON-RPC 原样转发给本机服务。
- **沙盒外 (`src/host.mjs` + `src/bridge.mjs`)**:由 macOS 菜单栏应用 `Gemini Terminal Bridge.app` 启动并守护。启动时先加载用户真实登录 Shell 的环境变量(`HOME`、`PATH` 含 Homebrew、`SSH_AUTH_SOCK`、代理变量等),再常驻运行一个 Desktop Commander 子进程。
- **断连不中断**:通过 `start_process` 启动的命令托管在沙盒外的常驻子进程里,Gemini 断开或重连后仍可通过 `read_process_output` 继续查看输出。

---

## 安装与部署

### 环境要求

- macOS 14+
- Node.js 20+(推荐 Homebrew 安装:`/opt/homebrew/bin/node`)
- Xcode Command Line Tools(用于编译菜单栏应用 `swiftc`,如未安装运行 `xcode-select --install`)

### 一键构建并安装

```bash
git clone https://github.com/Fangwenky/gemini-terminal-bridge.git
cd gemini-terminal-bridge
npm install
./scripts/install.sh
```

`install.sh` 会完成以下操作:

1. 编译 `app/HostApp.swift` 并安装到 `~/Applications/Gemini Terminal Bridge.app`。
2. 复制转发器到 `~/.local/share/gemini-mcp/terminal-bridge/proxy.mjs`。
3. 自动启动 `Gemini Terminal Bridge.app`,菜单栏会出现 **`>_`** 图标。

> 本项目仅提供终端能力,**不需要**授予 macOS「辅助功能」或「屏幕录制」权限。

### 菜单栏软件 (`>_`) 功能

点击顶部菜单栏 **`>_`** 图标可以:

- 查看后台服务状态(`● 服务运行中` / `○ 服务未运行`)
- **登录时启动**:建议勾选,重启 Mac 后自动在后台运行,无需手动打开
- **重启服务**:修改配置或环境变量后重启 `host.mjs`
- **编辑命令白/黑名单 (Desktop Commander)**:快速打开 `~/.claude-server-commander/config.json`
- **查看日志**:打开 `~/Library/Logs/GeminiTerminalBridge.log`

---

## Gemini 桌面端 MCP 配置规则

在 Gemini Mac 桌面端 → **任务模式** → **设置自定义的关联应用** → 选择 **本地 MCP**,按以下规则填写:

| 字段 | 填写内容 | 说明 |
|---|---|---|
| **选择设置方法** | `本地 MCP` | 不要选 Cloud MCP |
| **服务器名称** | `terminal` | 建议简短英文名,方便在对话中用 `@terminal` 或「用 terminal」提及 |
| **说明** | `在沙盒外运行本机完整终端(Desktop Commander)` | 可随意填写 |
| **命令** | `/opt/homebrew/bin/node /Users/<你的用户名>/.local/share/gemini-mcp/terminal-bridge/proxy.mjs` | **必须写完整绝对路径**,Node 路径与 `proxy.mjs` 路径之间用空格分隔(安装脚本结束时会打印可直接复制的完整命令) |
| **沙盒设置** | `默认` | **保持默认即可**,不需要切到「完整访问权限」 |

### 配置要点与注意事项

1. **命令栏必须使用绝对路径**:不要写 `node ~/.local/...`,因为 Gemini 任务沙盒下 `PATH` 和 `~` 展开不可靠;请直接使用 `install.sh` 输出的完整命令行。
2. **不要把 Node 路径填进「服务器名称」**:Node 路径和脚本路径必须一起填在「命令」栏。
3. **沙盒保持「默认」**:真正执行命令的是沙盒外的 `Gemini Terminal Bridge.app`,`proxy.mjs` 只需要本地回环网络和读取 `endpoint.json`,默认沙盒即可正常工作。
4. **移除旧配置避免冲突**:如果之前在 Gemini 里关联过直接运行的 `Desktop Commander`(带 `HOME=.../state` 的旧条目),建议删掉,避免模型误调用到受沙盒限制的旧条目。
5. **Gemini 会缓存工具列表**:Gemini 在点击「关联」时会把 MCP 的工具列表写入本地数据库缓存。以后只修改服务端内部逻辑无需重新关联;但如果升级 Desktop Commander 新增了工具,需要在 Gemini 中删除该 MCP 后重新关联一次。
6. **使用前提**:在 Gemini 中调用 `terminal` 前,需确保菜单栏 **`>_`** 处于运行状态(勾选「登录时启动」即可省心)。

---

## 验证安装

安装完成后,在终端运行端到端验证脚本(走的是和 Gemini 完全相同的 `proxy.mjs` 链路):

```bash
npm run smoke
```

脚本会依次检查:

- MCP 工具列表是否正常返回(25 个 Desktop Commander 工具)
- `HOME`、`PATH`(含 `git` / `node` / `brew` / `gh`)是否与本机登录 Shell 一致
- `/opt/homebrew` 是否可写
- `~/.ssh/known_hosts` 是否可读、`gh auth status` 是否已登录
- 模拟 MCP 连接断开再重连,确认后台长任务进程继续存活且输出完整

验证通过后,可在 Gemini 任务模式新开对话测试:

- `用 terminal 检查当前仓库的 git status 并执行 git push`
- `用 terminal 查看 brew --version 和 node -v`

---

## 安全说明

1. **本机隔离与鉴权**:`host.mjs` 仅监听 `127.0.0.1` 随机端口,每次启动生成 64 位随机 hex Bearer Token,写入 `~/.local/share/gemini-mcp/terminal-bridge/endpoint.json`(权限 `0600`),并拒绝携带 `Origin` 请求头的浏览器跨域请求。
2. **Gemini 逐次确认**:Gemini 任务模式在调用非只读工具前仍会弹窗要求点击「允许」,请在批准前核对即将执行的命令。
3. **命令黑名单**:由于沙盒外命令拥有与你本人终端相同的权限,建议在 `~/.claude-server-commander/config.json`(可通过菜单栏 `>_` → 编辑命令白/黑名单打开)中配置 `blockedCommands`,例如:

```json
{
  "blockedCommands": ["sudo", "rm -rf /", "shutdown", "reboot"]
}
```

---

## 环境变量与排查

### 可选环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `GTB_PORT` | `0`(随机端口) | 指定 `host.mjs` 监听端口 |
| `GTB_TOKEN` | 随机 64 位 hex | 自定义鉴权 Token |
| `GTB_ENDPOINT_DIR` | `~/.local/share/gemini-mcp/terminal-bridge` | `endpoint.json` 所在目录 |
| `GTB_ENDPOINT` | `$GTB_ENDPOINT_DIR/endpoint.json` | 供 `proxy.mjs` 读取的端点文件路径 |
| `GTB_COMMANDER_PATH` | `node_modules/@wonderwhy-er/desktop-commander/dist/index.js` | 自定义 Desktop Commander 入口路径 |
| `GTB_NODE` | `$(command -v node)` | `install.sh` 写入 App 配置的 Node 路径 |

### 常见问题

- **提示 `Gemini Terminal Bridge host unavailable`**:菜单栏 `>_` 未运行。从 `~/Applications/Gemini Terminal Bridge.app` 启动,或点击菜单栏 `>_` →「重启服务」。
- **新增了 PATH 或环境变量未生效**:`host.mjs` 在启动时读取一次登录 Shell 环境变量,修改 `~/.zshrc` 后点击菜单栏 `>_` →「重启服务」即可刷新。
- **查看运行日志**:`tail -n 50 ~/Library/Logs/GeminiTerminalBridge.log`。

## License

[MIT](LICENSE)