ConsoleSun/Gemini-Eyes

gemini-web-mcp

让 Agent 用上 Gemini 的「眼睛」和「手」 —— 一个 MCP 服务，把 gemini.google.com 网页端的能力桥接给任何 Agent：

• 🗣️ 对话：多轮聊天、续聊历史会话
• 👁️ 看图 / 看视频：上传本地文件，让 Gemini 识别并描述
• 🎨 生图（Imagen）/ 🎬 生视频（Veo）：自动下载成品到本地
• 💬 会话管理：列出 / 读取 / 删除账号下的历史对话
• 🔄 免维护登录态：后台每 25 分钟自动续期 Cookie，服务常驻就不过期

核心特点：不走官方 API——不需要 API Key、不产生 API 计费。它复用你浏览器里 已登录的 Google 会话 Cookie，重放网页端的内部请求，与你在浏览器里使用完全等价 （共享账号历史、共享生成额度）。

⚠️ 风险提示

本项目是对 Gemini 网页端内部接口的逆向封装，非官方 API；自动化访问可能违反 Google 服务条款，请合法使用、自行评估风险。请务必使用专用 Google 小号测试， 不要使用主力账号——这类操作有真实的封号风险，且不应用于商业用途或批量抓取。

快速开始

环境：Python ≥ 3.10，推荐 uv。

uv sync --extra dev        # 安装依赖

1. 准备 Cookie（二选一）

A. 自动提取：在 Chrome/Edge 登录 gemini.google.com 后关闭浏览器：

uv run python -m gemini_mcp.cookie_extractor --browser chrome --list --domain google.com

新版浏览器改用 portal/app-bound 加密无法离线解密时，程序会明确提示，改用方式 B。

B. 手动导出：用浏览器扩展（如 Cookie-Editor）导出 gemini.google.com 的全部 Cookie 为 JSON。全量导出、一个不落；其中 __Secure-1PSID 必带，浏览器里有 __Secure-1PSIDTS 则必须一起带。保存位置三选一：

• 默认路径 ~/.config/gemini-web-mcp/cookies.json —— 服务自动读取，零配置
• 任意路径 + 启动参数 --cookie-file /path/to/cookies.json
• 任意路径 + 环境变量 GEMINI_COOKIE_FILE

2. 启动服务

# stdio（大多数 MCP 客户端用这个）
uv run gemini-mcp --cookie-file cookies.json

# HTTP（供远程 Agent 或调试；默认开启 Bearer token 鉴权，启动时打印随机 token）
uv run gemini-mcp --cookie-file cookies.json --transport http --port 8900

3. 接入客户端

DeepSeek Harness（推荐）：仓库根目录带有 DSH bundle 清单，开箱即用——不设 环境变量时走「uv + Chrome 自动提取 Cookie」的零配置路径；需要自定义时，在启动 dsh web 前设置环境变量（任选）：

• GEMINI_EYES_UV —— uv 的绝对路径（默认：PATH 上的 uv）
• GEMINI_EYES_DIR —— 本仓库的绝对路径（默认：dsh 的当前工作目录）
• GEMINI_COOKIE_FILE —— 手动导出的 cookies.json 路径（默认： ~/.config/gemini-web-mcp/cookies.json，若存在；否则从 Chrome 自动提取）

dsh plugin --profile demo add github:ConsoleSun/Gemini-Eyes
dsh --profile demo

新开会话后工具以 mcp__gemini-web__* 出现。

Claude Desktop / Cline / 其他：标准 MCP 配置，command + args 指向 gemini-mcp --cookie-file /path/to/cookies.json（stdio），或 HTTP 模式填 http://127.0.0.1:8900/mcp 并带 Authorization: Bearer <token> 头。

工具一览（9 个）

工作原理（简版）

1. 反编译 Cookie：从本地浏览器配置解密出 Google 会话（支持 Windows DPAPI / macOS Keychain / Linux 三平台）
2. 换令牌：访问网页端提取会话令牌（CSRF、build label、session id），带 TTL 缓存
3. 调用内部 RPC：对话走 StreamGenerate 流式接口；会话管理走 batchexecute； 文件走两阶段 resumable 上传
4. 自动续期：__Secure-1PSIDTS 是短效令牌，服务每 25 分钟通过 RotateCookies 换新并写回 cookie 文件；换令牌失败时先续期再重试，实现自愈

常见问题

开发

uv run pytest    # 全部使用合成加密数据，无需真实浏览器或 Cookie

发布到 GitHub 后给仓库加上 dsh-plugin topic，即可进入官方发现列表。

安全提醒：解密后的 Cookie 等同账号凭证——--reveal 仅用于调试，输出勿提交 git、勿外传。本项目与 Google 无任何关联，网页端内部接口随时可能变动。