Gemini MCP

🚀 Gemini MCP Server

这是一个MCP（模型上下文协议）服务器，可用于访问谷歌的Gemini API。它能直接替代Codex MCP，且接口匹配。

🚀 快速开始

此Gemini MCP Server可帮助你轻松访问谷歌的Gemini API，为各类应用提供智能交互能力。以下是使用前的准备步骤。

✨ 主要特性

• gemini - 开启一个新的Gemini对话，并可配置上下文。
• gemini-reply - 继续多轮对话。
• gemini-image - 使用Nano Banana（Gemini原生图像生成功能）生成图像。
• gemini-video-generate - 使用Veo 3.1开始视频生成。
• gemini-video-check - 检查视频生成状态并获取已完成的视频。

📦 安装指南

npm install
npm run build

📚 详细文档

配置

创建一个 .env 文件或设置环境变量：

# 必需：你的谷歌Gemini API密钥
GEMINI_API_KEY=your_api_key_here

# 可选：覆盖默认模型（默认：gemini-3-pro-preview）
GEMINI_MODEL=gemini-3-pro-preview

你可以从 Google AI Studio 获取API密钥。

与Claude Code配合使用

将以下内容添加到你的MCP设置 (~/.claude/mcp.json) 中：

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["/path/to/gemini-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

工具使用说明

gemini

开启一个与Gemini的新对话。 参数：

• prompt（必需） - 初始提示信息
• cwd - 工作目录上下文
• sandbox - 访问策略："read-only"（只读）、"workspace-write"（工作区写入）或 "danger-full-access"（完全危险访问）
• base-instructions - 覆盖默认系统指令
• developer-instructions - 为模型提供额外上下文

返回值：响应文本和一个用于后续跟进的 conversationId。

gemini-reply

继续一个已有的对话。 参数：

• conversationId（必需） - 之前 gemini 调用返回的ID
• prompt（必需） - 你的跟进消息

gemini-image

使用Nano Banana（谷歌内置于Gemini的原生图像生成功能）生成图像。 模型：

• Nano Banana (gemini-2.5-flash-image) - 快速、经济高效（约 $0.04/张图像），适用于大多数用例
• Nano Banana Pro (gemini-3-pro-image-preview) - 高级模型，文本渲染效果更好，适用于信息图表、图表和文本较多的图像

自动检测：当你的提示包含以下关键词时，服务器会自动使用Nano Banana Pro：

• "nano banana pro"、"pro model"
• "infographic"（信息图表）、"diagram"（图表）、"chart"（图表）、"graph"（图形）
• "text"（文本）、"typography"（排版）、"font"（字体）、"lettering"（字母）
• "logo"（标志）、"brand"（品牌）、"poster"（海报）、"flyer"（传单）、"banner"（横幅）
• "slide"（幻灯片）、"presentation"（演示文稿）、"document"（文档）
• "high quality"（高质量）、"4k"、"detailed text"（详细文本）

参数：

• prompt（必需） - 要生成图像的描述
• numberOfImages - 生成图像的数量（1 - 4，默认：1）
• aspectRatio - 图像比例："1:1"、"3:4"、"4:3"、"9:16"、"16:9"
• usePro - 强制使用Nano Banana Pro（如果未指定，则根据提示自动检测）
• outputPath - 保存生成图像的目录

示例：

// 自动检测使用Pro模型
"Create an infographic showing the software development lifecycle"

// 显式请求使用Pro模型
{ "prompt": "A sunset over mountains", "usePro": true }

// 快速生成（默认）
"A cute cat wearing a hat"

gemini-video-generate

使用Veo 3.1（谷歌的高级视频生成模型）开始视频生成。 重要提示：视频生成是异步的。此工具会立即返回一个操作ID。使用 gemini-video-check 轮询完成状态（通常需要30 - 60秒）。 参数：

• prompt（必需） - 要生成视频的描述
• aspectRatio - 视频比例："16:9"（默认）、"9:16"
• resolution - 视频分辨率："480p"、"720p"（默认）
• firstFrameBase64 - 可选的Base64编码图像，用作第一帧（可先使用 gemini-image 生成）

返回值：用于检查状态的操作ID

示例工作流程：

1. gemini-video-generate: "A cat playing with a ball of yarn"
   → 返回: { operationId: "op-123..." }

2. 等待30 - 60秒

3. gemini-video-check: { operationId: "op-123..." }
   → 返回: { status: "processing", elapsed: "45s" }
   或者
   → 返回: { status: "complete", videoData: "..." }

gemini-video-check

检查视频生成操作的状态并获取已完成的视频。 参数：

• operationId - 来自 gemini-video-generate 的操作ID（可选 - 如果省略，则使用最后一个操作）
• outputPath - 保存已完成视频的目录

返回值：

• 如果正在处理：状态和已用时间
• 如果已完成：视频数据（Base64编码）和可选的保存文件路径

💡 使用建议：你可以使用 gemini-image 创建自定义第一帧，然后通过 firstFrameBase64 将其传递给 gemini-video-generate，以更好地控制你的视频。

开发

# 以开发模式运行
npm run dev

# 为生产环境构建
npm run build

# 启动生产服务器
npm start

📄 许可证

本项目采用MIT许可证。