Gemini Desktop MCP
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 Desktop MCP
通过本机已登录的 Gemini Windows 桌面客户端提供 Gemini 问答:MCP 调用方或本项目 CLI 提交任务,异步取得任务编号,持续查询并取回完整回答。独立任务进入新对话,可在上限内并行;续聊复用本服务保存的父任务会话。常规任务使用客户端页面和观察层,不使用 Playwright、窗口焦点、键鼠或剪贴板。
范围是 Gemini 问答。输入为任务文本和调用方明确提供的 TXT 材料;Gemini 不执行本地 shell,也不编辑本地文件。本项目不是通用自主编码代理,也不管理全部历史对话。
本项目不包含、不分发 Gemini 客户端或其安装包。固定支持 1.16.0 桌面客户端,使用前需要已登录的 Google 账号和可用网络。
要求
Windows 11(已实测),当前 Windows 用户已登录桌面。
Node.js 22.13 或更新版本。
自行准备合法来源的 Gemini Windows 桌面客户端 1.16.0,且文件须匹配本仓库基线。仓库不提供安装包,也不保证其他同名客户端兼容。
安装补丁前完全退出客户端,确认没有生成中的回答和未保存草稿。
Related MCP server: rbac-rag-assistant
安装(固定 1.16.0 基线)
桌面补丁只修改已知 1.16.0 安装目录中的应用包文件(resources/app.asar 及基线列出的 unpacked 资源),并用 desktop-baseline.json 校验版本与文件哈希。基线为 appVersion 1.16.0,实际运行时为 Electron 44.5.1。版本或哈希不符时停止,不修补未知版本。--assert-closed 表示调用方已人工确认客户端完整退出;脚本不会替你关闭窗口、保存或丢弃草稿。
在仓库根目录的 PowerShell 中执行:
npm ci
$install = Join-Path $env:LOCALAPPDATA 'Google/Gemini/app-1.16.0'
$staging = Join-Path (Get-Location) 'state/desktop-build'
node desktop-patch.cjs check --install-dir $install --json
node desktop-patch.cjs build --install-dir $install --staging $staging --writable --json
node desktop-patch.cjs install --install-dir $install --staging $staging --yes --assert-closed --jsoncheck 应返回 ok: true 且 issues 为空;安装后再次检查会显示 status: patched。客户端不在默认目录时,把 $install 改成实际安装目录。build 会重建 staging,staging 必须位于本项目 state/ 内。备份、安装清单与回滚记录在 state/desktop-backup/1.16.0。
安装后启动 Gemini,确认已登录并处于可用页面,然后执行:
node client.cjs health
node client.cjs connectconnect 只检查连接和页面可用性,不发送聊天消息。
恢复原厂客户端(沿用前面的 $install,或在新会话中重新设置):
node desktop-patch.cjs rollback --install-dir $install --yes --assert-closed --json升级本项目桥接代码前也要先回滚到库存 app.asar,再重新 build 和 install;build 只接受原始基线。客户端升级后版本或哈希变化时停止安装,不要沿用旧补丁。补丁会修改已安装客户端文件,可能影响官方支持状态;请自行评估并遵守 Google 的适用条款。
接入 MCP
按 mcp.example.toml 配置 MCP 客户端。示例采用 Codex 的 mcp_servers TOML 表;其他 MCP 客户端只需在各自的 stdio 配置中填入相同的 command、args 和环境变量。command 指向 Node 可执行文件,args 指向本仓库的 server.cjs。请把示例路径改成你自己的绝对路径。GEMINI_WORK_STATE 可省略,默认使用仓库下 state/desktop-v1;如保留或修改,必须与补丁使用的 --bridge-state 一致。不要使用别人机器上的路径或端口。
Codex 用户如已配置 [mcp_servers.gemini],可选择执行 ./activate.ps1 更新该节。它先核验桌面桥(必要时启动客户端),再使用当前 Node 和仓库实际路径生成配置,保留其他配置节,并把首次旧配置节备份到被忽略的 state/。配置以原子替换写入;若没有该节或存在嵌套 Gemini 配置表则停止,不修改配置,应改用模板手动配置。其他 MCP 客户端使用上述模板即可。
配置或升级后需要重载或重连 MCP 客户端,新增工具才会出现在工具列表中。server.cjs 按需启动后台进程,不需要单独常驻启动 MCP 服务。
使用
CLI 与 MCP 共用同一个持久化队列:
node client.cjs health
node client.cjs capabilities
node client.cjs submit request.json
node client.cjs wait task-id 1800
node client.cjs status task-id
node client.cjs result task-id
node client.cjs release task-id [reason]submit 立即返回任务编号;wait 等待并自动拼接分页,第二个参数是本次等待预算(秒,默认 1800),等待的是队列事件,到期只返回当前状态,不改变任务执行。把任务写入 request.json(字段可参考 request.example.json),任务正文示例:
{
"prompt": "用三句话概括附件中的要点。",
"mode": "chat",
"model": "hydrogen",
"files": ["C:/path/material.txt"]
}timeout_sec可选,范围 20–1800 秒,默认 1800 秒。这是从客户端首次执行开始的总预算,包含页面准备与生成,不包含排队;恢复原任务不重新计时。预算耗尽时保留部分回答和任务占用,继续观察真实完成或冲突,不重发。mode可用auto(默认,保持当前模式)、chat(对话)、task(任务)。对话模式会选择并核实“高”思考;任务模式没有思考等级入口,返回thinking_control=not_exposed、thinking_level=native,不冒充高思考。model默认hydrogen(4 Hydrogen)。也可填当前页面模型菜单中的唯一名称或完整条目标识,不依赖固定名单;旧别名只作兼容,不代表实时清单。指定模型缺失、歧义、禁用、锁定或升级入口时明确失败,不自动降级、不切换模式、不创建补做任务。续聊使用
continue_task_id指定已完成父任务;续聊继承父任务实际模式,同一会话不再点击模式切换。TXT 在提交时快照;相同任务编号与相同材料复用原任务,不同内容复用编号会被拒绝。附件只支持 TXT:最多 10 个,每个 10 MiB,总计 25 MiB。
MCP 工具为 gemini_connect / gemini_submit / gemini_status / gemini_wait / gemini_result / gemini_health / gemini_capabilities / gemini_release。典型顺序是 gemini_connect → gemini_submit → gemini_wait → gemini_result;gemini_result 返回 next_offset 时继续分页。gemini_status 可等待至多 20 秒;gemini_wait 按队列事件等待,不轮询页面。
能力查询
gemini_capabilities 无参数,查询已绑定的空闲主页面中的模型名称、可调用 selector、选中与受限状态,以及实际暴露的思考选项。仅 status=ready 且 observed=true 表示取得本次菜单事实,结果不跨请求缓存。活动任务或其他菜单操作期间返回 busy;草稿、附件、弹窗或用户已打开的菜单使查询返回 blocked;无法观察或确认清理时返回 unavailable。这些状态都不提供可用模型清单。
查询不会启动后台、发送消息、改变模型或思考选择;换文档或用户接手后停止点击。default_model 只说明默认选择政策,不保证账号可用;菜单选中也不代表本轮实际推理模型已核实。
状态与恢复
status / result / wait / health 附带 activity,用简明说明和 next_action 表达当前在等待什么。quiet 表示上次观察器检查可响应但没有新进展,awaiting_completion 表示已有回答但结束证据不足,observation_lost 表示观察检查失败,reconnecting 表示连接恢复中;这些都不会自动重发。任务依据标为 saved_task,时间来自已保存证据;健康检查标为 health_probe 或 health_snapshot,不能把旧记录当作本次探测成功。原有状态、错误码及恢复规则仍是执行依据。
状态 | 行为 |
queued / connecting / submitting / generating | 后台自动执行并保存结果;正常由推送事件驱动,不做周期性页面快照 |
retry_wait | 网络或地区异常,按 1、2、4、8、15、15 分钟有限退避 |
partial | 保存部分回答;预算耗尽时任务保留并继续观察,其他部分回答只恢复原会话 |
uncertain | 发送状态无法确定,只查询或恢复,绝不重发 |
needs_user_action | 处理登录、验证码、确认弹窗、草稿或冲突后调用 connect |
completed / failed | 任务结束,结果或失败原因保留 |
完成判定要求唯一的本轮任务标记、与标记严格配对的回答槽位、未截断且去除空白后非空的回答、当前没有 stop 控件、本轮回答内无生成信号,并保持 2 秒稳定。结束证据有两种:页面响应 complete=true;或仅在已核实的对话模式下,同一任务、同一已确认会话有唯一且有序的原生 start/complete 通知。原生通知在产生端记录文档与任务绑定,原厂无绑定通知只作诊断。任务模式和未知模式仍要求页面完成控件。原生通知、已有文字或停止按钮消失均不能单独触发完成。
长时间没有新事件时,后台执行一次空闲诊断:ping 观察器并检查最近推送状态,不读取页面。若已有回答但不满足完整结束证据,或观察不到新进度,任务保持 generating,状态中带 completion_unverified 和 diagnostic;gemini_wait / CLI wait 会立即返回 wait_reason,任务、原会话和执行状态均保留。
执行进程由轻量 supervisor 监控。进程退出或断线后继续使用原任务编号;队列和桥接各自记录发送边界。不能确认发送时,不通过新建会话规避。正常停止后台:创建 state/desktop-v1/stop-worker,等待 health 中 supervisor 和 worker 退出;恢复前删除该文件,再执行 connect。
needs_user_action 且尚未发出(send_state=not_sent)的失败任务,应先按错误码和账本查明原因;在补丁和后台未确认恢复前不要释放,也不要按同一编号重交。release 可同步已结束的桥记录或关闭从未发送的任务,但不终止已发送的生成。修复并确认当前连接健康后,可关闭明确未发送的失败记录;确需重新执行时使用新的任务编号。过期的重连或释放通知不要重复执行;以当前 health 和账本为准。
隐私与数据
任务
prompt和显式提供的 TXT 内容会通过已登录客户端发送到 Google Gemini,受 Google 的服务条款和账号设置约束。任务记录、部分回答、日志和队列保存在本机
state/desktop-v1。该目录已在.gitignore中,不应提交或公开。桌面桥只监听
127.0.0.1上的随机端口,Bearer 令牌随 Gemini 启动轮换并写入state/desktop-v1/discovery.json。调用方自动发现;不要把令牌写入聊天、文档或日志。本项目不导出浏览器 Cookie 或其他浏览器凭据,不打开调试端口,不自动同意新条款,不修改 VPN,也不会自动丢弃客户端草稿。
仓库不提供丢弃草稿、关闭客户端窗口或修改 VPN 的自动化命令;这些操作由使用者自行确认。
支持范围与已知限制
仅支持 Windows 和固定 1.16.0 桌面客户端;不自动适配新版本,版本或哈希变化时停止。
附件仅支持 TXT;不支持 PDF、图片或其他文件类型。
同时生成的任务上限为 3(含准备阶段);第四个任务排队。
只支持新建对话和本服务任务的续聊;列出、搜索、读取或续接任意历史会话不在当前范围。
不自动选择或回退模型,不自动路由,不自动创建补做任务,不自动重发发送状态不明的任务。
最小化窗口、真实网络故障、生成中客户端强制退出、执行进程或桥接任意崩溃组合尚未完整验收。
英文界面下「上传和工具」等入口尚未按中文界面同样的实况验证;未见过的异步文件选择路径仍可能弹出系统文件框。
页面是否暴露完成控件、菜单是否出现和平台实际推理模型都可能有未核实情形;完成状态表示本轮回答收取完成,不保证回答内容正确。
未覆盖无人登录、休眠或跨账号场景。
具体已实测范围和仍存在的缺口见 ACCEPTANCE.md。
文档
ACCEPTANCE.md:当前验证结论、使用限制和未完成验证。
docs/intention/task-service-intention.md:服务范围、已决定策略和不在范围的能力。
docs/specification/capabilities-and-activity.md:能力查询与
activity状态表达的当前契约。docs/survey/task-service-design-evidence.md:页面事实、源码机制和证据边界。
docs/survey/gemini-web-bridge-comparison.md:其他 Gemini 网页桥接方案的只读对照。
AGENTS.md:贡献者和维护者必须保留的安全与文档约定。
文档只保留当前有效内容;过期规则和旧批次不归档。清理文档不等于扩大已验证范围。
开发检查
npm ci
npm test离线测试覆盖包布局、认证、草稿保护、发送边界、附件快照、共享队列、完成判定、并发清理和监督进程。离线通过不能替代真实收发、后台运行、断线和回滚验收。
许可证
本项目源码以 MIT 许可证发布,版权归 2026 71oaix,全文见 LICENSE。Gemini 客户端、Google 服务及第三方依赖不包含在本许可证范围内,其权利归各自所有者。
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
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceConnects MCP clients to Gemini Cloud Assist APIs, enabling users to understand, manage, and troubleshoot their Google Cloud environment using natural language.72Apache 2.0
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to ask plain-language questions and receive answers grounded only in documents the configured role is cleared to read, with the same access-controlled tools available across any client.-
- AlicenseNot gradedqualityBmaintenanceEnables chat, document search (RAG), and a declarative SQL tool builder over MCP so any client can use these capabilities.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to queue coding, review, analysis, and image tasks through an existing authenticated browser chat session, then retrieve validated responses with code blocks and stored artifacts. Work runs through a persistent local queue with tools for status, cancellation, error inspection, and metrics.18 npm2GPL 3.0