Skip to main content
Glama
Gemini Terminal Bridge

Gemini Terminal Bridge

by Fangwenky

Gemini Terminal Bridge

让 Gemini Mac 桌面端(任务模式) 通过 MCP 稳定使用本机完整终端环境(基于 Desktop Commander),无需关闭 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 连接,沙盒内的子进程会一并丢失。

Related MCP server: DarwinRelay

架构原理

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

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)

一键构建并安装

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 链路):

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,例如:

{
  "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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers