GeminiDesktop GeminiDesktop
教程指南

GeminiDesktop MCP server：让 Claude Code / Cursor 直接调 Gemini 原生工具

发布于 · 作者： GeminiDesktop Team

GeminiDesktop MCP server：让 Claude Code / Cursor 直接调 Gemini 原生工具

结论先行： GeminiDesktop 把 Gemini 生态里最有价值的 9 个原生能力（chat / generate_image / generate_video / generate_music / tts / embed / generate_audio_overview / rag_index / rag_query）以一个 stdio MCP server 的形式暴露出来。只要你装了 GeminiDesktop.app，就自带了 CLI + MCP server，不用 npm publish、不用 pip install、不用写胶水代码。Claude Code 一行 claude mcp add 就能让 Claude 在写代码时顺手调用 Gemini 画图、生成视频、查询本地 RAG。

一句话总结： 单 binary 复用 GUI + CLI + MCP，Rust + rmcp + stdio 是目前最轻的实现方式；BYOK 用环境变量优先，Tauri store 做兜底；让 Claude Code 和 Cursor 真正拿到 Gemini 的原生工具，而不是再绕一圈 REST API。

MCP 生态现状：谁有 server 谁没有

MCP（Model Context Protocol）在 2024 年由 Anthropic 开源后，到 2026 年已经形成三层生态：

  • 官方示例层：Anthropic 在 github.com/modelcontextprotocol/servers 维护了 filesystem / github / slack / puppeteer 等官方 server，质量高但覆盖面窄。
  • 社区自建层：每个工具厂商自己写一个 MCP server，质量参差不齐。Gemini、Claude、OpenAI 都没有官方 MCP server，只能靠社区用 @modelcontextprotocol/sdk 包一层 REST API。
  • 产品自带层：像 Linear、Sentry 这种 SaaS 厂商把 MCP server 内嵌到自家产品里，用户装完客户端就直接有。

GeminiDesktop 选的是第三条路：把 MCP server 内嵌进桌面 App。装完 app 就自带 /Applications/GeminiDesktop.app/Contents/MacOS/GeminiDesktop mcp 这个入口，不需要额外下载。这对 Claude Code / Cursor 用户来说是最低摩擦的接入方式。

为什么选 Rust + rmcp crate + stdio

主流 MCP server 的实现栈有三条路径：

技术栈 启动时间 包体积 复用难度 适合场景
Node + @modelcontextprotocol/sdk 300-800ms（含 Node 冷启动） 需要单独打包 ~50MB 和桌面 App 分离 快速原型、纯独立 server
Python + mcp 500-1000ms 同样独立部署 同上 数据科学向
Rust + rmcp crate + stdio < 50ms 直接复用 GUI 的 binary，0 额外体积 和 GUI/CLI 同进程同代码 产品自带型 MCP

GeminiDesktop 本身就是 Tauri 2.x + Rust 的桌面 App，引入 rmcp crate（MCP 官方 Rust SDK）后，只需要在 main.rs 里加一个 mcp 子命令分支，所有的 Gemini API 调用逻辑和 GUI 共用一份——修一次 bug 三端同步生效。

stdio transport 的选择也很自然：Claude Code、Cursor、Continue 这些主流 MCP 客户端都默认拉起子进程走 stdio，不用搞 HTTP 端口和 OAuth。

单 binary 复用：装了 GeminiDesktop.app 就自带

传统做法是“下载 GUI + 另外 npm install @xxx/mcp-server”，用户要装两次、升级两次、配两次 API Key。GeminiDesktop 的做法：

# 装了 GeminiDesktop.app 后，同一个 binary 三种入口模式
/Applications/GeminiDesktop.app/Contents/MacOS/GeminiDesktop           # GUI 模式
/Applications/GeminiDesktop.app/Contents/MacOS/GeminiDesktop chat      # CLI 模式
/Applications/GeminiDesktop.app/Contents/MacOS/GeminiDesktop mcp       # MCP 模式

三种模式共享：

  • 配置：同一个 Tauri store（~/Library/Application Support/app.geminidesktop.desktop/）
  • API Key：GUI 里配置了，CLI 和 MCP 都能直接用
  • 模型缓存：Gemini API 的 model list、embedding cache、RAG 索引都共用
  • 升级：Tauri 自带 updater 更新 GUI 的时候，CLI 和 MCP 也一起更新

对用户来说：装一次，三端可用；不用 npm publish，也没有版本不一致的头疼。

暴露的 9 个工具

工具名 功能 典型场景
chat 普通对话 Claude 写代码时让 Gemini 做 code review 二次确认
generate_image Imagen / Nano Banana 2 出图 写博客时让 Claude 顺手生成配图
generate_video Veo 3 文生视频 产品 demo、Hero 视频片段
generate_music Lyria 生成背景音乐 视频配乐、podcast 片头
tts Gemini TTS（多音色、多语言） 把文章转 podcast、生成语音 demo
embed gemini-embedding-001（768 维） 在 Claude 侧做 RAG 预处理
generate_audio_overview NotebookLM 风格双人对谈播客 把长文或 PDF 变成 10 分钟通勤 podcast
rag_index 把文件/目录索引进本地 sqlite-vec Claude 维护的代码库建索引
rag_query 从本地 sqlite-vec 查询 top-k “在我的笔记里找一下 XXX 怎么实现的”

前 7 个是 Gemini 云端能力，后 2 个是 GeminiDesktop 独有的本地 RAG——不用上传文件，直接索引到本地 SQLite 文件。关于 RAG 的实现细节可以看 本地 sqlite-vec RAG：给 50 万字笔记建索引的 200 MB 文件。

Claude Code 一键装

Claude Code 从 0.6 开始支持 claude mcp add 命令行注册 MCP server。对 GeminiDesktop 用户：

# macOS
claude mcp add geminidesktop -- /Applications/GeminiDesktop.app/Contents/MacOS/GeminiDesktop mcp

# Windows
claude mcp add geminidesktop -- "C:\Program Files\GeminiDesktop\GeminiDesktop.exe" mcp

# 验证
claude mcp list
# 应该看到：geminidesktop (stdio) - 9 tools available

然后在任意 Claude Code 对话里：

> 帮我给刚写完的 README 配一张封面图，横图 1600x900

Claude 会自动选中 generate_image 工具，调用 Gemini 的 Nano Banana 2，把图片保存到项目里并在对话里贴出路径。整个过程不用离开 Claude Code 终端。

Cursor settings.json 一段

Cursor 从 0.46 开始原生支持 MCP。在 ~/.cursor/settings.json 里加一段：

{
  "mcp": {
    "servers": {
      "geminidesktop": {
        "command": "/Applications/GeminiDesktop.app/Contents/MacOS/GeminiDesktop",
        "args": ["mcp"],
        "env": {}
      }
    }
  }
}

对比 Claude Code 的差异：

  • Claude Code：用 claude mcp add CLI 注册，配置存在 ~/.claude/mcp.json
  • Cursor：手动编辑 settings.json，没有 CLI 管理命令
  • 通用：两边都是 stdio transport、都是同一个 binary、都共享同一个 API Key

Cursor Composer 模式下可以直接在 Cmd+I 对话里说 “generate an image of…”，Cursor 会自动调 MCP 工具。

BYOK 优先级：env var > .settings.json

GeminiDesktop 的 API Key 读取顺序：

  1. 环境变量 GEMINI_API_KEY（最高优先级）— 适合 CI、临时 override
  2. Tauri store (~/Library/Application Support/app.geminidesktop.desktop/config.json) — GUI 里配的持久化 key
  3. 报错提示，不 fallback 到 Google 托管 key（避免额度泄露）

这个顺序的好处：

  • Claude Code / Cursor 在 MCP 模式下如果你想用不同项目不同 key，直接在 shell 里 export GEMINI_API_KEY=xxx 再启动客户端即可
  • CI/团队共享：不用把 key 写进 Tauri store（会被 rsync 同步或误提交），只在环境变量里注入
  • 默认路径：个人用户 GUI 里配一次，CLI/MCP 全都走这个 key，零配置

实战：让 Gemini 在 Claude Code 里配图 + 查 RAG

一个典型的博客写作工作流：

[你]     我在写一篇 "如何用 React Server Components 做 AI 聊天"
         的博客草稿，先帮我从 ~/notes 里找之前写过的 RSC 相关笔记。

[Claude] 我调用 geminidesktop.rag_query...
         找到 3 条高度相关的笔记：
         1. 2025-11-20-rsc-streaming.md (score 0.89)
         2. 2025-09-03-ai-chat-patterns.md (score 0.84)
         3. 2026-02-14-use-server-actions.md (score 0.78)
         
         基于这些笔记，以下是博客大纲...

[你]     不错，给每个 H2 section 配一张封面图。

[Claude] 调用 geminidesktop.generate_image x 5...
         已生成 5 张图片，保存到 ./images/ 下。

整个过程 Claude 既有本地上下文（RAG 查询），又有 Gemini 的多模态能力（画图），而这一切都是通过 MCP 在一个 binary 里完成的——不用开另一个浏览器 tab、不用切换 API Key、不用写任何胶水代码。

更多工程细节可以看 官方网站 geminidesktop.app 以及 如何把 Claude Code Skills 迁移到 GeminiDesktop。

常见问题

Q1: MCP server 和 Gemini REST API 有什么区别？

A: REST API 需要你自己在客户端写 fetch、处理 auth、管理 rate limit。MCP server 把这些封装成“工具”，由 Claude Code / Cursor 根据对话上下文自动调用，不用写代码。

Q2: 不装 GeminiDesktop 能用这个 MCP server 吗？

A: 暂时不行。我们的设计是“GUI + CLI + MCP 共用一个 binary”，这样能最大化复用配置和缓存。如果你坚持只要 MCP，可以从 GitHub release 下 headless 版本，但不会有 auto-update。

Q3: Windows / Linux 支持吗？

A: macOS 和 Windows 原生支持。Linux 目前是社区维护的 AppImage，MCP 模式同样可用。

立即访问