Gemini Terminal Bridge
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Gemini Terminal Bridge
让 Gemini Mac 桌面端(任务模式) 通过 MCP 稳定使用本机完整终端环境(基于 Desktop Commander),无需关闭 Gemini 默认沙盒,也不需要任何辅助功能或屏幕录制权限。
解决什么问题
直接在 Gemini 任务模式里挂载本地终端 MCP(如 Desktop Commander)时,会受到 Gemini 任务沙盒的限制:
无法使用 SSH / Git 凭据:沙盒禁止读取
~/.ssh/known_hosts和私钥,且部分配置会覆盖HOME,导致git push、ssh、gh失败。无法写入系统/工具目录:
brew install、npm install -g写入/opt/homebrew返回Operation not permitted。长任务断连即中断:安装或构建耗时较长时,一旦 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.shinstall.sh 会完成以下操作:
编译
app/HostApp.swift并安装到~/Applications/Gemini Terminal Bridge.app。复制转发器到
~/.local/share/gemini-mcp/terminal-bridge/proxy.mjs。自动启动
Gemini Terminal Bridge.app,菜单栏会出现>_图标。
本项目仅提供终端能力,不需要授予 macOS「辅助功能」或「屏幕录制」权限。
菜单栏软件 (>_) 功能
点击顶部菜单栏 >_ 图标可以:
查看后台服务状态(
● 服务运行中/○ 服务未运行)登录时启动:建议勾选,重启 Mac 后自动在后台运行,无需手动打开
重启服务:修改配置或环境变量后重启
host.mjs编辑命令白/黑名单 (Desktop Commander):快速打开
~/.claude-server-commander/config.json查看日志:打开
~/Library/Logs/GeminiTerminalBridge.log
Gemini 桌面端 MCP 配置规则
在 Gemini Mac 桌面端 → 任务模式 → 设置自定义的关联应用 → 选择 本地 MCP,按以下规则填写:
字段 | 填写内容 | 说明 |
选择设置方法 |
| 不要选 Cloud MCP |
服务器名称 |
| 建议简短英文名,方便在对话中用 |
说明 |
| 可随意填写 |
命令 |
| 必须写完整绝对路径,Node 路径与 |
沙盒设置 |
| 保持默认即可,不需要切到「完整访问权限」 |
配置要点与注意事项
命令栏必须使用绝对路径:不要写
node ~/.local/...,因为 Gemini 任务沙盒下PATH和~展开不可靠;请直接使用install.sh输出的完整命令行。不要把 Node 路径填进「服务器名称」:Node 路径和脚本路径必须一起填在「命令」栏。
沙盒保持「默认」:真正执行命令的是沙盒外的
Gemini Terminal Bridge.app,proxy.mjs只需要本地回环网络和读取endpoint.json,默认沙盒即可正常工作。移除旧配置避免冲突:如果之前在 Gemini 里关联过直接运行的
Desktop Commander(带HOME=.../state的旧条目),建议删掉,避免模型误调用到受沙盒限制的旧条目。Gemini 会缓存工具列表:Gemini 在点击「关联」时会把 MCP 的工具列表写入本地数据库缓存。以后只修改服务端内部逻辑无需重新关联;但如果升级 Desktop Commander 新增了工具,需要在 Gemini 中删除该 MCP 后重新关联一次。
使用前提:在 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
安全说明
本机隔离与鉴权:
host.mjs仅监听127.0.0.1随机端口,每次启动生成 64 位随机 hex Bearer Token,写入~/.local/share/gemini-mcp/terminal-bridge/endpoint.json(权限0600),并拒绝携带Origin请求头的浏览器跨域请求。Gemini 逐次确认:Gemini 任务模式在调用非只读工具前仍会弹窗要求点击「允许」,请在批准前核对即将执行的命令。
命令黑名单:由于沙盒外命令拥有与你本人终端相同的权限,建议在
~/.claude-server-commander/config.json(可通过菜单栏>_→ 编辑命令白/黑名单打开)中配置blockedCommands,例如:
{
"blockedCommands": ["sudo", "rm -rf /", "shutdown", "reboot"]
}环境变量与排查
可选环境变量
变量 | 默认值 | 说明 |
|
| 指定 |
| 随机 64 位 hex | 自定义鉴权 Token |
|
|
|
|
| 供 |
|
| 自定义 Desktop Commander 入口路径 |
|
|
|
常见问题
提示
Gemini Terminal Bridge host unavailable:菜单栏>_未运行。从~/Applications/Gemini Terminal Bridge.app启动,或点击菜单栏>_→「重启服务」。新增了 PATH 或环境变量未生效:
host.mjs在启动时读取一次登录 Shell 环境变量,修改~/.zshrc后点击菜单栏>_→「重启服务」即可刷新。查看运行日志:
tail -n 50 ~/Library/Logs/GeminiTerminalBridge.log。
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Remote MCP for Gemini upgrade evals, prompt regressions, output diffs, and eval receipts.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to execute terminal commands in a controlled workspace via the Model Context Protocol.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP agents to control macOS natively with shell, PTY, background Chrome automation, and Accessibility-based desktop control.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables Gemini Spark to securely read, edit, and search a selected local workspace, execute shell commands, and integrate development tools via MCP with user approval safeguards.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables local project file access, editing, command execution, recoverable long-running jobs, Apple MPS checks, and macOS UI automation through MCP.MIT