MCP Gemini Server

Name: MCP Gemini Server
Author: bsmi021

本地服务

github.com/bsmi021AI 与智能体3674 周前更新

代码仓库

关于 MCP Gemini Server

MCP Gemini Server 是一个基于 @google/genai SDK（v0.10.0）的 MCP 服务，将 Google Gemini 的能力封装为标准 MCP 工具。它面向需要把 Gemini 作为后端模型调用的其他 LLM 或 MCP 兼容系统。项目侧重基于 URL 的多媒体分析，不支持直接上传文件。

主要功能

01封装 @google/genai SDK 的 Gemini 生成与流式输出
02支持函数调用与有状态的多轮对话
03基于公开 URL 分析图片和 YouTube 视频
04缓存内容的创建、查询、更新与删除
05通过 Gemini 2.0 Flash 生成图像

适用场景

01为 Cline 或 Claude 等客户端提供 Gemini 后端能力
02分析公开网页图片或 YouTube 教学视频
03复用缓存提示词以减少重复请求内容

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 gemini_generateContent、gemini_startChat 等工具。它还包含 MCP 客户端功能，可连接外部 MCP 服务并调用其工具。

#ai #mcp #gemini #claude #gemini-api #mcp-server #modelcontextprotocol #mcp-gemini #google-gemini

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "gemini-server": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli"
      ]
    }
  }
}

启动命令npx -y @smithery/cli

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@smithery/clistdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MCP Gemini Server

概述

此项目提供一个专用的 MCP（模型上下文协议）服务，用于封装 @google/genai SDK（v0.10.0）。它将 Google 的 Gemini 模型功能作为标准 MCP 工具开放，使其他大模型（如 Claude）或兼容 MCP 的系统能够利用 Gemini 的功能，将其作为后端主力。

此服务旨在通过提供由 MCP 标准管理的一致工具接口，简化与 Gemini 模型的集成。它支持最新的 Gemini 模型，包括 gemini-1.5-pro-latest、gemini-1.5-flash 和 gemini-2.5-pro。

**重要说明：**此服务不支持直接上传文件，而是专注于通过 URL 分析图像和视频等多媒体内容。处理文本内容时，请使用标准内容生成工具。

文件上传与基于 URL 的分析

❌ 不支持：直接上传文件

此 MCP Gemini Server 不支持以下文件上传操作：

本地文件上传：无法将本地文件系统中的文件上传到 Gemini
Base64 编码文件：无法处理 Base64 编码的图像或视频数据
二进制文件数据：无法处理原始文件字节或二进制数据
文件引用：无法处理已上传内容的文件 ID 或引用
音频文件上传：无法直接上传并转录音频文件

不支持文件上传的原因：

架构简化，专注于基于 URL 的处理
避免处理文件的复杂性，增强安全性
降低存储和带宽需求
简化代码库维护

✅ 完全支持：基于 URL 的多媒体分析

此服务完全支持分析来自公开可访问 URL 的多媒体内容：

通过 URL 分析图像：

公开图像 URL：分析托管在任何公开可访问 Web 服务器上的图像
支持的格式：通过直接 URL 访问 PNG、JPEG、WebP、HEIC、HEIF
多张图像：在单个请求中处理多个图像 URL
安全验证：自动验证 URL 并进行安全筛查

YouTube 视频分析：

公开 YouTube 视频：全面分析任何公开的 YouTube 视频内容
视频理解：提取见解、摘要和详细分析
教育内容：非常适合分析教程、讲座和教育视频
多个视频：处理多个 YouTube URL（使用 Gemini 2.5+ 时，每个请求最多 10 个）

网页内容处理：

HTML 内容：分析网页并从中提取信息
混合媒体：将文本内容与嵌入的图像和视频结合
上下文分析：结合文本提示词处理 URL，实现全面分析

本地内容的替代方案

如果要分析本地文件：

托管到 Web 服务器：将文件上传到公共 Web 服务器，并使用 URL
使用云存储：将文件上传到 Google Drive、Dropbox 或 AWS S3 等服务，并设置为公开访问
使用 GitHub：将图片托管在 GitHub 仓库中，并使用原始文件 URL
使用图片托管服务：将图片上传到 Imgur、ImageBB 或类似平台

对于音频内容：

使用外部转录服务（Whisper API、Google Speech-to-Text 等）
将音频上传到 YouTube，并分析生成的视频 URL
使用其他专门处理音频的 MCP 服务

功能

**核心生成：**支持标准文本生成（gemini_generateContent）和流式文本生成（gemini_generateContentStream），并支持系统指令和缓存内容。
**函数调用：**允许 Gemini 模型请求执行客户端定义的函数（gemini_functionCall）。
**有状态聊天：**跨多轮对话管理对话上下文（gemini_startChat、gemini_sendMessage、gemini_sendFunctionResult），并支持系统指令、工具和缓存内容。
**基于 URL 的多媒体分析：**分析来自公共 URL 的图片和 YouTube 视频，无需上传文件。不支持直接上传文件。
**缓存：**创建、列出、检索、更新和删除缓存内容，以优化提示词，并支持工具和工具配置。
**图像生成：**使用 Gemini 2.0 Flash Experimental（gemini_generateImage）根据文本提示词生成图片，并可控制分辨率、图片数量和负面提示词。还支持最新的 Imagen 3.1 模型，以高质量专用图像生成功能和高级风格控制来生成图片。请注意，Gemini 2.5 模型（Flash 和 Pro）目前不支持图像生成。
**URL 上下文处理：**直接从 URL 获取并分析 Web 内容，并提供高级安全性、缓存和内容处理功能。
- gemini_generateContent：增强了 URL 上下文支持，可在提示词中包含 Web 内容
- gemini_generateContentStream：集成 URL 上下文的流式生成
- gemini_url_analysis：用于高级 URL 内容分析的专用工具，支持多种分析类型
**MCP 客户端：**连接并与外部 MCP 服务交互。
- mcpConnectToServer：与外部 MCP 服务建立连接。
- mcpListServerTools：列出已连接 MCP 服务上可用的工具。
- mcpCallServerTool：调用已连接 MCP 服务上的函数，并可选择输出到文件。
- mcpDisconnectFromServer：断开与外部 MCP 服务的连接。
- writeToFile：将内容直接写入允许的目录中的文件。

前置条件

Node.js（v18 或更高版本）
Google AI Studio API 密钥（https://aistudio.google.com/app/apikey）。
- 重要：缓存 API 仅兼容 Google AI Studio API 密钥，使用 Vertex AI 凭据时不受支持。此服务目前不支持 Vertex AI 身份验证。

安装与设置

手动安装

**克隆/放置项目：**确保系统可以访问 mcp-gemini-server 项目目录。
**安装依赖：**在终端中进入项目目录并运行：
```
npm install
```
**构建项目：**编译 TypeScript 源代码：
```
npm run build
```
此命令使用 TypeScript 编译器（tsc），并将 JavaScript 文件输出到 ./dist 目录（由 tsconfig.json 中的 outDir 指定）。主服务入口文件为 dist/server.js。
**生成连接令牌：**创建一个强度高且唯一的连接令牌，用于在 MCP 客户端和服务之间进行安全通信。这是一个共享密钥，由你生成并分别配置在服务端和客户端。 使用以下任一方法生成安全令牌：

选项 A：使用 Node.js crypto（推荐）
```
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
选项 B：使用 OpenSSL
```
openssl rand -hex 32
```
选项 C：使用 PowerShell（Windows）
```
[System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
```
选项 D：在线生成器（谨慎使用） 使用 1Password 或 Bitwarden 等信誉良好的密码生成器，生成一个 64 个字符的随机字符串。

重要安全须知：
- 令牌长度至少应为 32 个字符，并包含随机字符
- 切勿分享此令牌，也不要将其提交到版本控制中
- 为每个服务实例使用不同的令牌
- 安全地存储令牌（例如，使用环境变量、密钥管理器等）
- 保存此令牌——服务器和客户端配置中都必须使用完全相同的值

配置 MCP 客户端：将服务配置添加到 MCP 客户端的设置文件中（例如，Cline/VSCode 使用 cline_mcp_settings.json，Claude Desktop App 使用 claude_desktop_config.json）。将 /path/to/mcp-gemini-server 替换为系统上的实际绝对路径，将 YOUR_API_KEY 替换为 Google AI Studio 密钥，并将 YOUR_GENERATED_CONNECTION_TOKEN 替换为你在第 4 步中生成的令牌。

{
  "mcpServers": {
    "gemini-server": { // Or your preferred name
      "command": "node",
      "args": ["/path/to/mcp-gemini-server/dist/server.js"], // Absolute path to the compiled server entry point
      "env": {
        "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY",
        "MCP_SERVER_HOST": "localhost",       // Required: Server host
        "MCP_SERVER_PORT": "8080",            // Required: Server port  
        "MCP_CONNECTION_TOKEN": "YOUR_GENERATED_CONNECTION_TOKEN", // Required: Use the token from step 4
        "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash", // Optional: Set a default model
        // Optional security configurations removed - file operations no longer supported
        "ALLOWED_OUTPUT_PATHS": "/var/opt/mcp-gemini-server/outputs,/tmp/mcp-gemini-outputs" // Optional: Comma-separated list of allowed output directories for mcpCallServerTool and writeToFileTool
      },
      "disabled": false,
      "autoApprove": []
    }
    // ... other servers
  }
}

重要说明：

args 中的路径必须是已编译的 dist/server.js 文件的绝对路径
除非 NODE_ENV 设置为 test，否则必须配置 MCP_SERVER_HOST、MCP_SERVER_PORT 和 MCP_CONNECTION_TOKEN
MCP_CONNECTION_TOKEN 必须与第 4 步中生成的令牌完全相同
确保路径存在，并且已使用 npm run build 构建服务

**重启 MCP 客户端：**重启 MCP 客户端应用程序（例如，安装了 Cline 扩展的 VS Code、Claude Desktop App），以加载新的服务配置。MCP 客户端会负责启动和停止服务进程。

配置

服务器通过 MCP 设置中的 env 对象传入环境变量进行配置：

GOOGLE_GEMINI_API_KEY（必需）：从 Google AI Studio 获取的 API 密钥。
GOOGLE_GEMINI_MODEL（可选）：指定默认的 Gemini 模型名称（例如，gemini-1.5-flash、gemini-1.0-pro）。设置后，需要模型名称的工具（如 gemini_generateContent、gemini_startChat 等）会在工具调用中省略 modelName 参数时使用此默认值。如果主要使用一个模型，这样可以简化客户端调用。如果未设置此环境变量，这些工具就必须提供 modelName 参数。可参阅 Google AI 文档，了解可用的模型名称。
ALLOWED_OUTPUT_PATHS（可选）：以逗号分隔的绝对路径列表，指定允许 mcpCallServerTool（使用 outputToFile 参数时）和 writeToFileTool 写入文件的目录。未设置时，这些工具将禁用文件输出。这是一项安全措施，用于防止任意文件写入。

可用工具

此服务器提供以下 MCP 工具。参数架构使用 Zod 定义，用于验证和描述。

**验证和错误处理：**所有参数都会在 MCP 工具层和服务层使用 Zod 架构进行验证，从而提供一致的验证、详细的错误消息和类型安全保障。服务器实现了全面的错误映射，以提供清晰且可执行的错误消息。

**重试逻辑：**对于临时错误（网络问题、速率限制、超时），API 请求会自动使用指数退避重试，以提高不稳定连接下的可靠性。重试机制包含可配置的最大尝试次数、延迟时间和抖动参数，以防止惊群效应。

**可选参数说明：**许多工具接受复杂的可选参数（例如，generationConfig、safetySettings、toolConfig、history、functionDeclarations、contents）。这些参数通常是对象或数组，其结构与底层 @google/genai SDK（v0.10.0）中定义的类型一致。如需了解这些复杂参数的确切结构和可用字段，请参阅： 1. 本项目中对应的 src/tools/*Params.ts 文件。 2. 官方 Google AI JS SDK 文档。

核心生成

gemini_generateContent
- 描述： 根据提示词生成非流式文本内容，并可选择支持 URL 上下文。
- 必需参数： prompt（字符串）
- 可选参数：
  - modelName（字符串）- 要使用的模型名称
  - generationConfig（对象）- 控制温度、topP 等生成参数
    - thinkingConfig（对象）- 控制模型推理过程
      - thinkingBudget（数字）- 推理的最大令牌数（0-24576）
      - reasoningEffort（字符串）- 简化控制：“none”（0 个令牌）、“low”（1K）、“medium”（8K）、“high”（24K）
  - safetySettings（数组）- 按危害类别控制内容过滤
  - systemInstruction（字符串或对象）- 引导模型行为的系统指令
  - cachedContentName（字符串）- 此请求要使用的缓存内容标识符
  - urlContext（对象）- 从 URL 获取并纳入网页内容
    - urls（数组）- 要获取并作为上下文纳入的 URL（最多 20 个）
    - fetchOptions（对象）- URL 获取配置
      - maxContentKb（数字）- 每个 URL 的最大内容大小，单位为 KB（默认值：100）
      - timeoutMs（数字）- 每个 URL 的获取超时时间，单位为毫秒（默认值：10000）
      - includeMetadata（布尔值）- 在上下文中纳入 URL 元数据（默认值：true）
      - convertToMarkdown（布尔值）- 将 HTML 转换为 markdown（默认值：true）
      - allowedDomains（数组）- 此请求允许的特定域名
      - userAgent（字符串）- URL 请求使用的自定义 User-Agent 标头
  - modelPreferences（对象）- 模型选择偏好
- 注意： 支持多模态输入、缓存内容和 URL 上下文，可生成全面的内容
- 推理预算： 控制模型推理的令牌预算。较低的值可加快响应速度，较高的值可提升复杂推理能力。
gemini_generateContentStream
- 描述： 使用 Server-Sent Events（SSE）以流式方式生成文本内容，实现实时内容交付，并支持 URL 上下文。
- 必需参数： prompt（字符串）
- 可选参数：
  - modelName（字符串）- 要使用的模型名称
  - generationConfig（对象）- 控制温度、topP 等生成参数
    - thinkingConfig（对象）- 控制模型推理过程
      - thinkingBudget（数字）- 推理的最大令牌数（0-24576）
      - reasoningEffort（字符串）- 简化控制：“none”（0 个令牌）、“low”（1K）、“medium”（8K）、“high”（24K）
  - safetySettings（数组）- 按危害类别控制内容过滤
  - systemInstruction（字符串或对象）- 引导模型行为的系统指令
  - cachedContentName（字符串）- 此请求要使用的缓存内容标识符
  - urlContext（对象）- 与 gemini_generateContent 相同的 URL 上下文选项
  - modelPreferences（对象）- 模型选择偏好

函数调用

gemini_functionCall
- 描述： 向模型发送提示词和函数声明，并返回文本响应或请求的函数调用对象（JSON 字符串）。
- 必需参数： prompt（字符串）、functionDeclarations（数组）
- 可选参数：
  - modelName（字符串）- 要使用的模型名称
  - generationConfig（对象）- 控制生成参数
  - safetySettings（数组）- 控制内容过滤
  - toolConfig（对象）- 配置工具行为，例如温度和置信度阈值

有状态聊天

gemini_startChat
- 说明： 启动新的有状态聊天会话，并返回唯一的 sessionId。
- 可选参数：
  - modelName（string）- 要使用的模型名称
  - history（array）- 初始对话历史记录
  - tools（array）- 工具定义，包括函数声明
  - generationConfig（object）- 控制生成参数
    - thinkingConfig（object）- 控制模型的推理过程
      - thinkingBudget（number）- 推理的最大令牌数（0-24576）
      - reasoningEffort（string）- 简化控制方式："none"（0 个令牌）、"low"（1K）、"medium"（8K）、"high"（24K）
  - safetySettings（array）- 控制内容过滤
  - systemInstruction（string 或 object）- 用于引导模型行为的系统指令
  - cachedContentName（string）- 要在此会话中使用的缓存内容标识符
gemini_sendMessage
- 说明： 在现有聊天会话中发送消息。
- 必需参数： sessionId（string）、message（string）
- 可选参数：
  - generationConfig（object）- 控制生成参数
    - thinkingConfig（object）- 控制模型的推理过程
      - thinkingBudget（number）- 推理的最大令牌数（0-24576）
      - reasoningEffort（string）- 简化控制方式："none"（0 个令牌）、"low"（1K）、"medium"（8K）、"high"（24K）
  - safetySettings（array）- 控制内容过滤
  - tools（array）- 工具定义，包括函数声明
  - toolConfig（object）- 配置工具行为
  - cachedContentName（string）- 要在此消息中使用的缓存内容标识符
gemini_sendFunctionResult
- 说明： 将函数执行结果发送回聊天会话。
- 必需参数： sessionId（string）、functionResponse（string）- 函数执行结果
- 可选参数： functionCall（object）- 对原始函数调用的引用
gemini_routeMessage
- 说明： 根据消息内容，将消息路由到所提供列表中最合适的模型。返回模型的响应以及所选模型。
- 必需参数：
  - message（string）- 要路由到最合适模型的文本消息
  - models（array）- 用于路由选择的模型名称数组（例如，['gemini-1.5-flash', 'gemini-1.5-pro']）。列表中的第一个模型将用于做出路由决策。
- 可选参数：
  - routingPrompt（string）- 用于路由决策的自定义提示词。如果未提供，将使用默认路由提示词。
  - defaultModel（string）- 路由失败时的备用模型。如果未提供且路由失败，将抛出错误。
  - generationConfig（object）- 应用于所选模型响应的生成配置设置。
    - thinkingConfig（object）- 控制模型的推理过程
      - thinkingBudget（number）- 推理的最大令牌数（0-24576）
      - reasoningEffort（string）- 简化控制方式："none"（0 个令牌）、"low"（1K）、"medium"（8K）、"high"（24K）
  - safetySettings（array）- 应用于路由和最终响应的安全设置。
  - systemInstruction（string 或 object）- 路由后用于引导模型行为的系统指令。

远程文件操作（已移除）

注意： 此服务不再支持直接文件上传操作。服务现在专注于基于 URL 的图像和视频多媒体分析，以及基于文本的内容生成。

替代方案：

图像分析： 使用可公开访问的图像 URL 和 gemini_generateContent 或 gemini_url_analysis 工具
视频分析： 使用可公开访问的 YouTube 视频 URL 进行内容分析
音频内容： 不支持通过文件上传进行音频转录——可考虑使用提供音频转录文本的基于 URL 的服务
文档分析： 使用基于 URL 的文档分析，或将文档转换为可公开访问的格式

缓存（需要 Google AI Studio 密钥）

gemini_createCache
- 说明： 为兼容的模型（例如 gemini-1.5-flash）创建缓存内容。
- 必需参数： contents（数组）、model（字符串）
- 可选参数：
  - displayName（字符串）——缓存内容的易读名称
  - systemInstruction（字符串或对象）——应用于缓存内容的系统指令
  - ttl（字符串——例如 '3600s'）——缓存内容的存活时间
  - tools（数组）——供缓存内容使用的工具定义
  - toolConfig（对象）——工具配置
gemini_listCaches
- 说明： 列出现有的缓存内容。
- 必需参数： 无
- 可选参数： pageSize（数字）、pageToken（字符串——注意：目前可能无法可靠地返回 pageToken）。
gemini_getCache
- 说明： 获取指定缓存内容的元数据。
- 必需参数： cacheName（字符串——例如 cachedContents/abc123xyz）
gemini_updateCache
- 说明： 更新缓存内容的元数据和内容。
- 必需参数： cacheName（字符串）、contents（数组）
- 可选参数：
  - displayName（字符串）——更新后的显示名称
  - systemInstruction（字符串或对象）——更新后的系统指令
  - ttl（字符串）——更新后的存活时间
  - tools（数组）——更新后的工具定义
  - toolConfig（对象）——更新后的工具配置
gemini_deleteCache
- 说明： 删除缓存内容。
- 必需参数： cacheName（字符串——例如 cachedContents/abc123xyz）

图像生成

gemini_generateImage
- 说明： 使用可用的图像生成模型，根据文本提示词生成图像。
- 必需参数： prompt（字符串——用于图像生成的描述性文本提示词）
- 可选参数：
  - modelName（字符串——默认使用 "imagen-3.1-generate-003" 进行高质量专用图像生成；也可使用 "gemini-2.0-flash-exp-image-generation" 调用 Gemini 模型）
  - resolution（字符串枚举："512x512"、"1024x1024"、"1536x1536"）
  - numberOfImages（数字——1-8，默认值：1）
  - safetySettings（数组）——控制生成图像的内容过滤
  - negativePrompt（字符串——指定生成图像中应避免的特征）
  - stylePreset（字符串枚举："photographic"、"digital-art"、"cinematic"、"anime"、"3d-render"、"oil-painting"、"watercolor"、"pixel-art"、"sketch"、"comic-book"、"neon"、"fantasy"）
  - seed（数字——用于可复现生成的整数值）
  - styleStrength（数字——风格预设强度，0.0-1.0）
- 响应： 返回一个 base64 编码图像数组，并附带尺寸和 MIME 类型等元数据。
- 注意： 图像生成会消耗大量资源，尤其是在使用较高分辨率时。可考虑使用较低分辨率，以加快响应速度并减少资源消耗。

音频转录（已移除）

注意： 此服务器不再支持通过直接上传文件进行音频转录。服务器专注于基于 URL 的图像和视频多媒体分析。

音频内容的替代方案：

YouTube 视频： 使用 YouTube 视频分析功能分析包含音频的视频内容
外部服务： 使用专用音频转录服务，并将其输出作为文本内容进行分析
基于 URL 的音频： 如果音频内容可通过受支持格式的公开 URL 获取，可考虑先使用外部转录服务，再分析生成的文本

URL 内容分析

gemini_url_analysis
- 描述： 高级 URL 分析工具，可获取网页内容并执行专门的分析任务，同时提供全面的安全和性能优化。
- 必需参数：
  - urls（数组）— 要分析的 URL（支持 1-20 个 URL）
  - analysisType（字符串枚举）— 要执行的分析类型：
    - summary — 全面总结内容
    - comparison — 比较多个 URL 的内容
    - extraction — 提取结构化信息
    - qa — 基于问题的内容分析
    - sentiment — 分析情感倾向
    - fact-check — 评估可信度
    - content-classification — 对主题和类型进行分类
    - readability — 分析易读性和复杂度
    - seo-analysis — 评估搜索优化效果
- 可选参数：
  - query（字符串）— 针对此次分析的具体查询或指令
  - extractionSchema（对象）— 用于提取结构化数据的 JSON 架构
  - questions（数组）— 要回答的具体问题列表（用于问答分析）
  - compareBy（数组）— 使用比较分析时要比较的具体方面
  - outputFormat（字符串枚举："text"、"json"、"markdown"、"structured"）— 所需的输出格式
  - includeMetadata（布尔值）— 是否在分析中包含 URL 元数据（默认值：true）
  - fetchOptions（对象）— 高级 URL 获取选项（与 urlContext fetchOptions 相同）
  - modelName（字符串）— 要使用的特定 Gemini 模型（未指定时自动选择）
- 安全功能： 多层 URL 验证、域名限制、私有网络保护和速率限制
- 性能功能： 智能缓存、并发处理，以及根据内容复杂度选择最优模型

MCP 客户端工具

mcpConnectToServer
- 描述： 与外部 MCP 服务建立连接，并返回连接 ID。
- 必需参数：
  - serverId（字符串）：此服务连接的唯一标识符。
  - connectionType（字符串枚举："sse" | "stdio"）：要使用的传输协议。
  - sseUrl（字符串，如果 connectionType 为 "stdio"，则为可选）：SSE 连接的 URL。
  - stdioCommand（字符串，如果 connectionType 为 "sse"，则为可选）：用于建立 stdio 连接的命令。
  - stdioArgs（字符串数组，可选）：stdio 命令的参数。
  - stdioEnv（对象，可选）：stdio 命令的环境变量。
- 重要： 此工具会返回一个 connectionId，后续调用 mcpListServerTools、mcpCallServerTool 和 mcpDisconnectFromServer 时必须使用该 ID。此 connectionId 在内部生成，与 serverId 参数不同。
mcpListServerTools
- 描述： 列出已连接的 MCP 服务上可用的工具。
- 必需参数：
  - connectionId（字符串）：由 mcpConnectToServer 返回的连接标识符。
mcpCallServerTool
- 描述： 调用已连接的 MCP 服务上的函数。
- 必需参数：
  - connectionId（字符串）：由 mcpConnectToServer 返回的连接标识符。
  - toolName（字符串）：要在远程服务上调用的工具名称。
  - toolArgs（对象）：传递给远程工具的参数。
- 可选参数：
  - outputToFile（字符串）：如果提供，工具的输出将写入此文件路径。该路径必须位于 ALLOWED_OUTPUT_PATHS 环境变量指定的某个目录中。
mcpDisconnectFromServer
- 描述： 断开与外部 MCP 服务的连接。
- 必需参数：
  - connectionId（字符串）：由 mcpConnectToServer 返回的连接标识符。
writeToFile
- 描述： 将内容直接写入文件。
- 必需参数：
  - filePath（字符串）：要写入文件的绝对路径。必须位于 ALLOWED_OUTPUT_PATHS 环境变量指定的某个目录中。
  - content（字符串）：要写入文件的内容。
- 可选参数：
  - overwrite（布尔值，默认值：false）：如果为 true，则覆盖已存在的文件。否则，如果文件已存在，则会抛出错误。

使用示例

以下示例展示了 MCP 客户端（如 Claude）如何使用 use_mcp_tool 格式调用这些工具：

示例 1：简单内容生成（使用默认模型）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Write a short poem about a rubber duck."
    }
  </arguments>
</use_mcp_tool>

示例 2：内容生成（指定模型和配置）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-1.0-pro",
      "prompt": "Explain the concept of recursion in programming.",
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 500
      }
    }
  </arguments>
</use_mcp_tool>

示例 2b：通过控制思考预算生成内容

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-1.5-pro",
      "prompt": "Solve this complex math problem: Find all values of x where 2sin(x) = x^2-x+1 in the range [0, 2π].",
      "generationConfig": {
        "temperature": 0.2,
        "maxOutputTokens": 1000,
        "thinkingConfig": {
          "thinkingBudget": 8192
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 2c：通过简化的推理力度设置生成内容

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-1.5-pro",
      "prompt": "Solve this complex math problem: Find all values of x where 2sin(x) = x^2-x+1 in the range [0, 2π].",
      "generationConfig": {
        "temperature": 0.2,
        "maxOutputTokens": 1000,
        "thinkingConfig": {
          "reasoningEffort": "high"
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 3：开始并继续聊天

开始聊天：

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_startChat</tool_name>
  <arguments>
    {}
  </arguments>
</use_mcp_tool>

（假设响应包含 sessionId: "some-uuid-123"）

发送消息：

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_sendMessage</tool_name>
  <arguments>
    {
      "sessionId": "some-uuid-123",
      "message": "Hello! Can you tell me about the Gemini API?"
    }
  </arguments>
</use_mcp_tool>

示例 4：使用系统指令生成内容（简化格式）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-2.5-pro-exp",
      "prompt": "What should I do with my day off?",
      "systemInstruction": "You are a helpful assistant that provides friendly and detailed advice. You should focus on outdoor activities and wellness."
    }
  </arguments>
</use_mcp_tool>

示例 5：使用系统指令生成内容（对象格式）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-1.5-pro-latest",
      "prompt": "What should I do with my day off?",
      "systemInstruction": {
        "parts": [
          {
            "text": "You are a helpful assistant that provides friendly and detailed advice. You should focus on outdoor activities and wellness."
          }
        ]
      }
    }
  </arguments>
</use_mcp_tool>

示例 6：使用带系统指令的缓存内容

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "modelName": "gemini-2.5-pro-exp",
      "prompt": "Explain how these concepts relate to my product?",
      "cachedContentName": "cachedContents/abc123xyz",
      "systemInstruction": "You are a product expert who explains technical concepts in simple terms."
    }
  </arguments>
</use_mcp_tool>

示例 6：生成图像

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateImage</tool_name>
  <arguments>
    {
      "prompt": "A futuristic cityscape with flying cars and neon lights",
      "modelName": "gemini-2.0-flash-exp-image-generation",
      "resolution": "1024x1024",
      "numberOfImages": 1,
      "negativePrompt": "dystopian, ruins, dark, gloomy"
    }
  </arguments>
</use_mcp_tool>

示例 6b：使用 Imagen 3.1 生成高质量图像

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateImage</tool_name>
  <arguments>
    {
      "prompt": "A futuristic cityscape with flying cars and neon lights",
      "modelName": "imagen-3.1-generate-003",
      "resolution": "1024x1024",
      "numberOfImages": 4,
      "negativePrompt": "dystopian, ruins, dark, gloomy"
    }
  </arguments>
</use_mcp_tool>

示例 6c：使用高级风格选项

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateImage</tool_name>
  <arguments>
    {
      "prompt": "A futuristic cityscape with flying cars and neon lights",
      "modelName": "imagen-3.1-generate-003",
      "resolution": "1024x1024",
      "numberOfImages": 2,
      "stylePreset": "anime",
      "styleStrength": 0.8,
      "seed": 12345
    }
  </arguments>
</use_mcp_tool>

示例 7：模型之间的消息路由

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_routeMessage</tool_name>
  <arguments>
    {
      "message": "Can you create a detailed business plan for a sustainable fashion startup?",
      "models": ["gemini-1.5-pro", "gemini-1.5-flash", "gemini-2.5-pro"],
      "routingPrompt": "Analyze this message and determine which model would be best suited to handle it. Consider: gemini-1.5-flash for simpler tasks, gemini-1.5-pro for balanced capabilities, and gemini-2.5-pro for complex creative tasks.",
      "defaultModel": "gemini-1.5-pro",
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 1024
      }
    }
  </arguments>
</use_mcp_tool>

响应将是一个 JSON 字符串，其中包含文本回复以及所选模型：

{
  "text": "# Business Plan for Sustainable Fashion Startup\n\n## Executive Summary\n...",
  "chosenModel": "gemini-2.5-pro"
}

示例 8：使用 URL 上下文生成内容

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Summarize the main points from these articles and compare their approaches to sustainable technology",
      "urlContext": {
        "urls": [
          "https://example.com/sustainable-tech-2024",
          "https://techblog.com/green-innovation"
        ],
        "fetchOptions": {
          "maxContentKb": 150,
          "includeMetadata": true,
          "convertToMarkdown": true
        }
      },
      "modelPreferences": {
        "preferQuality": true,
        "taskType": "reasoning"
      }
    }
  </arguments>
</use_mcp_tool>

示例 9：高级 URL 分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_url_analysis</tool_name>
  <arguments>
    {
      "urls": ["https://company.com/about", "https://company.com/products"],
      "analysisType": "extraction",
      "extractionSchema": {
        "companyName": "string",
        "foundedYear": "number",
        "numberOfEmployees": "string",
        "mainProducts": "array",
        "headquarters": "string",
        "financialInfo": "object"
      },
      "outputFormat": "json",
      "query": "Extract comprehensive company information including business details and product offerings"
    }
  </arguments>
</use_mcp_tool>

示例 10：多 URL 内容比较

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_url_analysis</tool_name>
  <arguments>
    {
      "urls": [
        "https://site1.com/pricing",
        "https://site2.com/pricing", 
        "https://site3.com/pricing"
      ],
      "analysisType": "comparison",
      "compareBy": ["pricing models", "features", "target audience", "value proposition"],
      "outputFormat": "markdown",
      "includeMetadata": true
    }
  </arguments>
</use_mcp_tool>

示例 11：带安全限制的 URL 内容

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze the content from these trusted news sources",
      "urlContext": {
        "urls": [
          "https://reuters.com/article/tech-news",
          "https://bbc.com/news/technology"
        ],
        "fetchOptions": {
          "allowedDomains": ["reuters.com", "bbc.com"],
          "maxContentKb": 200,
          "timeoutMs": 15000,
          "userAgent": "Research-Bot/1.0"
        }
      }
    }
  </arguments>
</use_mcp_tool>

基于 URL 的图像分析示例

这些示例展示了如何使用 Gemini 的原生图像理解能力分析公开 URL 中的图像。服务会从 URL 获取图像，并将其转换为 Gemini API 所需的格式。请注意，此服务不支持直接上传文件——所有图像分析都必须使用可公开访问的图像 URL。

示例 17：基本图像描述与分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Please describe this image in detail, including objects, people, colors, setting, and any text you can see.",
      "urlContext": {
        "urls": ["https://example.com/images/photo.jpg"],
        "fetchOptions": {
          "includeMetadata": true,
          "timeoutMs": 15000
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 18：对象检测与识别

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Identify and list all objects visible in this image. For each object, describe its location, size relative to other objects, and any notable characteristics.",
      "urlContext": {
        "urls": ["https://example.com/images/scene.png"],
        "fetchOptions": {
          "includeMetadata": false,
          "timeoutMs": 20000
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 19：图表与数据可视化分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze this chart or graph. What type of visualization is it? What are the main data points, trends, and insights? Extract any numerical values, labels, and time periods shown.",
      "urlContext": {
        "urls": ["https://example.com/charts/sales-data.png"]
      },
      "modelPreferences": {
        "preferQuality": true,
        "taskType": "reasoning"
      }
    }
  </arguments>
</use_mcp_tool>

示例 20：图像对比分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Compare these two images side by side. Describe the differences and similarities in terms of objects, composition, colors, style, and any other notable aspects.",
      "urlContext": {
        "urls": [
          "https://example.com/before-renovation.jpg",
          "https://example.com/after-renovation.jpg"
        ],
        "fetchOptions": {
          "maxContentKb": 200,
          "includeMetadata": true
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 21：图像文本提取（OCR）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Extract all text visible in this image. Include any signs, labels, captions, or written content. Maintain the original formatting and structure as much as possible.",
      "urlContext": {
        "urls": ["https://example.com/documents/screenshot.png"]
      }
    }
  </arguments>
</use_mcp_tool>

示例 22：技术示意图或流程图分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze this technical diagram, flowchart, or schematic. Explain the system architecture, identify components, describe the relationships and data flow, and interpret any symbols or notations used.",
      "urlContext": {
        "urls": ["https://docs.example.com/architecture-diagram.png"],
        "fetchOptions": {
          "maxContentKb": 100,
          "includeMetadata": true
        }
      },
      "modelPreferences": {
        "preferQuality": true,
        "taskType": "reasoning"
      }
    }
  </arguments>
</use_mcp_tool>

示例 23：针对具体问题的图像分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Looking at this image, please answer these specific questions: 1) What is the main subject? 2) What colors dominate the scene? 3) Are there any people visible? 4) What appears to be the setting or location? 5) What mood or atmosphere does the image convey?",
      "urlContext": {
        "urls": ["https://example.com/images/landscape.jpg"]
      }
    }
  </arguments>
</use_mcp_tool>

示例 24：带安全限制的图像分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze the composition and design elements in this image, focusing on visual hierarchy, layout principles, and aesthetic choices.",
      "urlContext": {
        "urls": ["https://trusted-cdn.example.com/design-mockup.jpg"],
        "fetchOptions": {
          "allowedDomains": ["trusted-cdn.example.com", "assets.example.com"],
          "maxContentKb": 150,
          "timeoutMs": 25000,
          "includeMetadata": false
        }
      }
    }
  </arguments>
</use_mcp_tool>

基于 URL 的图像分析注意事项：

支持的格式：PNG、JPEG、WebP、HEIC、HEIF（符合 Gemini API 规范）
图像访问：图像必须可通过公开 URL 访问，且无需身份验证
尺寸注意事项：Gemini 会自动分区处理大型图像
处理方式：服务会从 URL 获取图像，并将其转换为 Gemini API 所需的格式
安全性：服务会施加限制，以防止访问私有网络或恶意域名
性能：由于处理复杂度较高，高分辨率图像的分析可能需要更长时间
Token 使用量：图像尺寸会影响 Token 消耗量——图像越大，消耗的 Token 越多

YouTube 视频分析示例

这些示例展示了如何使用 Gemini 的视频理解能力分析 YouTube 视频。服务可以通过提供公开可访问的 YouTube 视频 URL 来处理视频。请注意，此服务仅支持公开的 YouTube 视频——无法分析私有、未公开列出或受地区限制的视频。

示例 25：基本 YouTube 视频分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Please analyze this YouTube video and provide a comprehensive summary including the main topics discussed, key points, and overall theme.",
      "urlContext": {
        "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
        "fetchOptions": {
          "includeMetadata": true,
          "timeoutMs": 30000
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 26：提取 YouTube 视频内容并附上时间戳

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze this educational YouTube video and create a detailed outline with key topics and approximate timestamps. Identify the main learning objectives and key concepts covered.",
      "urlContext": {
        "urls": ["https://www.youtube.com/watch?v=EXAMPLE_VIDEO_ID"],
        "fetchOptions": {
          "maxContentKb": 300,
          "includeMetadata": true,
          "timeoutMs": 45000
        }
      },
      "modelPreferences": {
        "preferQuality": true,
        "taskType": "reasoning"
      }
    }
  </arguments>
</use_mcp_tool>

示例 27：针对具体问题的 YouTube 视频分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Watch this YouTube video and answer these specific questions: 1) What is the main message or thesis? 2) Who is the target audience? 3) What evidence or examples are provided? 4) What are the key takeaways? 5) How is the content structured?",
      "urlContext": {
        "urls": ["https://www.youtube.com/watch?v=EXAMPLE_VIDEO_ID"]
      }
    }
  </arguments>
</use_mcp_tool>

示例 28：多个 YouTube 视频的对比分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Compare and contrast these YouTube videos. Analyze their different approaches to the topic, presentation styles, key arguments, and conclusions. Identify similarities and differences in their perspectives.",
      "urlContext": {
        "urls": [
          "https://www.youtube.com/watch?v=VIDEO_ID_1",
          "https://www.youtube.com/watch?v=VIDEO_ID_2"
        ],
        "fetchOptions": {
          "maxContentKb": 400,
          "includeMetadata": true,
          "timeoutMs": 60000
        }
      },
      "modelPreferences": {
        "preferQuality": true,
        "taskType": "reasoning"
      }
    }
  </arguments>
</use_mcp_tool>

示例 29：YouTube 视频技术分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze this technical YouTube tutorial and extract step-by-step instructions, identify required tools or materials, note any code examples or commands shown, and highlight important warnings or best practices mentioned.",
      "urlContext": {
        "urls": ["https://www.youtube.com/watch?v=TECH_TUTORIAL_ID"],
        "fetchOptions": {
          "includeMetadata": true,
          "timeoutMs": 40000
        }
      }
    }
  </arguments>
</use_mcp_tool>

示例 30：YouTube 视频情感与风格分析

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_url_analysis</tool_name>
  <arguments>
    {
      "urls": ["https://www.youtube.com/watch?v=EXAMPLE_VIDEO_ID"],
      "analysisType": "sentiment",
      "outputFormat": "structured",
      "query": "Analyze the tone, mood, and presentation style of this YouTube video. Assess the speaker's credibility, engagement level, and overall effectiveness of communication."
    }
  </arguments>
</use_mcp_tool>

示例 31：YouTube 视频教育内容评估

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Evaluate this educational YouTube video for accuracy, clarity, and pedagogical effectiveness. Identify the teaching methods used, assess how well complex concepts are explained, and suggest improvements if any.",
      "urlContext": {
        "urls": ["https://www.youtube.com/watch?v=EDUCATIONAL_VIDEO_ID"],
        "fetchOptions": {
          "maxContentKb": 250,
          "includeMetadata": true
        }
      },
      "modelPreferences": {
        "preferQuality": true,
        "taskType": "reasoning"
      }
    }
  </arguments>
</use_mcp_tool>

示例 32：带域名安全限制的 YouTube 视频

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_generateContent</tool_name>
  <arguments>
    {
      "prompt": "Analyze the content and key messages of this YouTube video, focusing on factual accuracy and source credibility.",
      "urlContext": {
        "urls": ["https://www.youtube.com/watch?v=TRUSTED_VIDEO_ID"],
        "fetchOptions": {
          "allowedDomains": ["youtube.com", "www.youtube.com"],
          "maxContentKb": 200,
          "timeoutMs": 35000,
          "includeMetadata": true
        }
      }
    }
  </arguments>
</use_mcp_tool>

YouTube 视频分析注意事项：

仅限公开视频：只能分析可公开访问的 YouTube 视频
URL 格式：使用标准 YouTube URL（youtube.com/watch?v=VIDEO_ID 或 youtu.be/VIDEO_ID）
处理时间：视频分析通常比文本或图像分析耗时更长
内容限制：超长视频的内容可能会被截断或分段处理
元数据：当 includeMetadata: true 时，会包含视频元数据（标题、描述、时长）
语言支持：Gemini 可以分析多种语言的视频
内容限制：服务对 URL 内容施加与其他内容相同的安全限制
Token 使用量：根据视频长度和复杂度，视频分析可能消耗大量 Token

支持的多媒体分析用例

MCP Gemini Server 通过基于 URL 的处理方式，利用 Google Gemini 先进的视觉与视频理解能力，支持全面的多媒体分析。以下按内容类型列出了主要用例：

图像分析用例

内容理解：

产品分析：分析产品图像中的特征、设计元素并评估质量
文档 OCR：从文档、收据和表单的图像中提取并转录文本
图表分析：解读数据可视化内容、提取关键见解并说明趋势
技术图示：理解架构图、流程图和技术示意图
医学图像：分析医学图表、X 光片和诊断图像（仅用于教育目的）
艺术与设计：分析艺术构图、配色方案和设计原则

比较分析：

前后对比：比较多张图像，识别变化和差异
产品比较：分析多张产品图像，比较产品特征
A/B 测试：评估设计变体和视觉差异

安全与质量：

内容审核：识别不当或有害的视觉内容
质量评估：评估图像质量、分辨率和技术特性
品牌合规性：检查图像是否符合品牌指南

视频分析用例

教育内容：

讲座分析：提取关键概念、创建摘要并标记重要时间戳
教程理解：拆解分步说明并突出关键流程
培训材料：分析企业培训视频并提取学习目标
学术研究：处理研究演示文稿并提取研究方法

内容创作：

视频摘要：为长篇视频内容生成简洁摘要
转录生成：生成详细的转录文本并识别说话者
内容分类：按主题、流派或内容类型对视频进行分类
情感分析：评估情绪基调和受众参与度指标

技术分析：

软件演示：提取软件功能和使用说明
产品评测：分析产品演示视频并提取关键见解
故障排除指南：解析技术支持视频，提取问题解决步骤
代码评审：分析编程教程视频并提取代码示例

商业情报：

市场研究：分析宣传视频和营销内容
竞争分析：研究竞争对手的视频内容和策略
客户反馈：处理视频证言和反馈交流
活动报道：分析会议演示和主题演讲

集成能力

多模态分析：

将文本提示词与图片／视频 URL 结合，用于上下文分析
在单个请求中处理多种媒体类型，以获得全面的见解
将视觉内容与文本指令交叉参考

工作流集成：

链接多个分析操作，以构建复杂工作流
将结果导出到文件，以便进一步处理
与外部 MCP 服务集成，以扩展功能

安全与性能：

验证 URL 并进行安全筛查，确保内容处理安全
支持缓存经常分析的内容
支持批量处理多个媒体项

示例 12：连接到外部 MCP 服务（SSE）

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>mcpConnectToServer</tool_name>
  <arguments>
    {
      "serverId": "my-external-server",
      "connectionType": "sse",
      "sseUrl": "http://localhost:8080/mcp"
    }
  </arguments>
</use_mcp_tool>

（假设响应包含一个唯一的连接 ID，例如：connectionId: "12345-abcde-67890"）

示例 13：调用外部 MCP 服务上的工具并将输出写入文件

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>mcpCallServerTool</tool_name>
  <arguments>
    {
      "connectionId": "12345-abcde-67890", // Use the connectionId returned by mcpConnectToServer
      "toolName": "remote_tool_name",
      "toolArgs": { "param1": "value1" },
      "outputToFile": "/var/opt/mcp-gemini-server/outputs/result.json"
    }
  </arguments>
</use_mcp_tool>

重要提示：MCP 客户端工具中使用的 connectionId 必须是 mcpConnectToServer 返回的连接标识符，而不是原始的 serverId 参数。

注意：outputToFile 路径必须位于 ALLOWED_OUTPUT_PATHS 环境变量指定的某个目录中。例如，如果 ALLOWED_OUTPUT_PATHS="/path/to/allowed/output,/another/allowed/path"，则文件路径必须是这些路径之一的子目录。

示例 14：将内容直接写入文件

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>writeToFile</tool_name>
  <arguments>
    {
      "filePath": "/path/to/allowed/output/my_notes.txt",
      "content": "This is some important content.",
      "overwrite": true
    }
  </arguments>
</use_mcp_tool>

**注意：**与 mcpCallServerTool 一样，filePath 必须位于 ALLOWED_OUTPUT_PATHS 环境变量指定的某个目录中。这是一项关键的安全功能，可防止未经授权的文件写入。

`mcp-gemini-server` 与 Gemini SDK 的 MCP 函数调用

Google Gemini API 官方文档包含一些示例（例如使用 MCP 结构进行函数调用），展示了如何使用客户端 Gemini SDK（例如 Python 或 Node.js 中的 SDK）与 Gemini API 交互。在这类场景中，尤其是进行函数调用时，可以使用客户端 SDK 来构造请求并处理响应，使其符合 MCP 原则。

mcp-gemini-server 项目提供了一种互补的方案：它是一个完整实现的独立 MCP 服务。客户端应用无需直接使用 Gemini SDK 为 Gemini API 格式化符合 MCP 风格的消息，而是可以（使用其他大模型，例如 Claude、自定义脚本或任何兼容 MCP 的系统）：

连接到此 mcp-gemini-server 的一个实例。
调用此服务提供的预定义 MCP 工具，例如 gemini_functionCall、gemini_generateContent 等。

随后，mcp-gemini-server 会在内部处理与 Google Gemini API 交互所需的一切工作，包括构造请求、管理 API 密钥和处理响应，从而将这些细节从 MCP 客户端中抽象出来。

使用 `mcp-gemini-server` 的优势：

**抽象与简化：**客户端应用无需直接集成 Gemini SDK，也无需管理其 MCP 风格交互的 API 细节。它们只需进行标准的 MCP 工具调用。
**集中配置：**API 密钥、默认模型选择、安全设置和其他配置均由 mcp-gemini-server 集中管理。
**丰富的工具集：**提供一系列用于 Gemini 各种功能的预定义 MCP 工具（文本生成、聊天、文件处理、图像生成等），而不仅限于函数调用。
**互操作性：**让任何兼容 MCP 的客户端都能使用 Gemini 的能力，无需原生支持 Gemini SDK。

何时选择哪种方式：

直接使用 SDK（如 Google 的 MCP 示例）：
- 适用于构建客户端应用（例如使用 Python 或 Node.js），并希望在客户端中直接精细控制与 Gemini API 的交互。
- 如果你希望在客户端应用中管理 Gemini SDK 依赖项和逻辑，并且主要关注以类似 MCP 的方式构建函数调用，这种方式会很有用。
使用 mcp-gemini-server：
- 如果你希望将 Gemini 功能提供给现有的兼容 MCP 的生态系统（例如另一个大模型或工作流自动化系统），这是理想选择。
- 如果你希望快速构建原型或将 Gemini 功能部署为工具，而不需要在客户端进行大量 SDK 集成，这种方式很有帮助。
- 如果你需要将更广泛的 Gemini 功能作为一致的 MCP 工具提供，并希望集中管理与 Gemini API 的交互入口，这种方式更合适。

关于此服务自身 MCP 客户端工具的说明：

mcp-gemini-server 还包含 mcpConnectToServer、mcpListServerTools 和 mcpCallServerTool 等工具。这些工具允许此服务充当 MCP 客户端，连接到其他外部 MCP 服务。这与 MCP 客户端连接到 mcp-gemini-server 以使用 Gemini 功能，是两种不同的能力。

环境变量

必需：

GOOGLE_GEMINI_API_KEY：你的 Google Gemini API 密钥（必需）

生产环境必需（除非 NODE_ENV=test）：

MCP_SERVER_HOST：服务主机地址（例如，“localhost”）
MCP_SERVER_PORT：网络传输使用的端口（例如，“8080”）
MCP_CONNECTION_TOKEN：客户端连接到此服务时必须提供的强且唯一的共享密钥令牌。此令牌并非由 Google 或任何外部服务提供，你必须使用加密安全的方法自行生成。生成方法请参阅安装说明（第 4 步）。服务端和所有连接的客户端必须使用完全相同的令牌。

可选 - Gemini API 配置：

GOOGLE_GEMINI_MODEL：要使用的默认模型（例如，gemini-1.5-pro-latest、gemini-1.5-flash）
GOOGLE_GEMINI_DEFAULT_THINKING_BUDGET：用于控制模型推理的默认思考预算（以令牌为单位，0-24576）

可选 - URL 上下文配置：

GOOGLE_GEMINI_ENABLE_URL_CONTEXT：启用 URL 上下文功能（选项：true、false；默认值：false）
GOOGLE_GEMINI_URL_MAX_COUNT：每个请求允许的最大 URL 数量（默认值：20）
GOOGLE_GEMINI_URL_MAX_CONTENT_KB：每个 URL 的最大内容大小（KB）（默认值：100）
GOOGLE_GEMINI_URL_FETCH_TIMEOUT_MS：每个 URL 的获取超时时间（毫秒）（默认值：10000）
GOOGLE_GEMINI_URL_ALLOWED_DOMAINS：允许的域名列表，以逗号分隔或使用 JSON 数组（默认值：*，表示所有域名）
GOOGLE_GEMINI_URL_BLOCKLIST：屏蔽的域名列表，以逗号分隔或使用 JSON 数组（默认值：空）
GOOGLE_GEMINI_URL_CONVERT_TO_MARKDOWN：将 HTML 内容转换为 Markdown（选项：true、false；默认值：true）
GOOGLE_GEMINI_URL_INCLUDE_METADATA：在上下文中包含 URL 元数据（选项：true、false；默认值：true）
GOOGLE_GEMINI_URL_ENABLE_CACHING：启用 URL 内容缓存（选项：true、false；默认值：true）
GOOGLE_GEMINI_URL_USER_AGENT：URL 请求使用的自定义 User-Agent 标头（默认值：MCP-Gemini-Server/1.0）

可选 - 安全配置：

ALLOWED_OUTPUT_PATHS：允许 mcpCallServerTool（使用 outputToFile 参数时）和 writeToFileTool 等工具写入文件的目录绝对路径列表，以逗号分隔。这是一项关键安全功能，可防止未经授权的文件写入。如果未设置，这些工具将禁用文件输出。

可选 — 服务配置：

MCP_CLIENT_ID：此服务作为客户端连接其他 MCP 服务时使用的默认客户端 ID（默认为 "gemini-sdk-client"）
MCP_TRANSPORT：MCP 服务使用的传输方式（可选：stdio、sse、streamable、http；默认：stdio）
- 重要：SSE（服务器发送事件）并未弃用，仍是 MCP 协议的重要组成部分
- SSE 对双向通信尤其有用，可支持动态工具更新和采样等功能
- 每种传输类型在 MCP 生态系统中都有特定的适用场景
MCP_LOG_LEVEL：MCP 操作的日志级别（可选：debug、info、warn、error；默认：info）
MCP_ENABLE_STREAMING：为 HTTP 传输启用 SSE 流式传输（可选：true、false；默认：false）
MCP_SESSION_TIMEOUT：HTTP 传输的会话超时时间，单位为秒（默认：3600 = 1 小时）
SESSION_STORE_TYPE：会话存储后端（memory 或 sqlite；默认：memory）
SQLITE_DB_PATH：使用 sqlite 存储时 SQLite 数据库文件的路径（默认：./data/sessions.db）

可选 — GitHub 集成：

GITHUB_API_TOKEN：用于访问 GitHub API 的个人访问令牌（GitHub 代码审查功能必需）。对于公共仓库，令牌需要具有 'public_repo' 和 'read:user' 权限范围。对于私有仓库，令牌需要具有 'repo' 权限范围。

可选 — 旧版服务配置（已弃用）：

MCP_TRANSPORT_TYPE：已弃用 — 请改用 MCP_TRANSPORT
MCP_WS_PORT：已弃用 — 请改用 MCP_SERVER_PORT
ENABLE_HEALTH_CHECK：启用健康检查服务（可选：true、false；默认：true）
HEALTH_CHECK_PORT：健康检查 HTTP 服务的端口（默认：3000）

你可以在根目录中创建一个 .env 文件，并填入这些变量：

# Required API Configuration
GOOGLE_GEMINI_API_KEY=your_api_key_here

# Required for Production (unless NODE_ENV=test)
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8080
MCP_CONNECTION_TOKEN=your_secure_token_here

# Optional API Configuration
GOOGLE_GEMINI_MODEL=gemini-1.5-pro-latest
GOOGLE_GEMINI_DEFAULT_THINKING_BUDGET=4096

# Security Configuration
ALLOWED_OUTPUT_PATHS=/var/opt/mcp-gemini-server/outputs,/tmp/mcp-gemini-outputs   # For mcpCallServerTool and writeToFileTool

# URL Context Configuration
GOOGLE_GEMINI_ENABLE_URL_CONTEXT=true  # Enable URL context features
GOOGLE_GEMINI_URL_MAX_COUNT=20          # Maximum URLs per request
GOOGLE_GEMINI_URL_MAX_CONTENT_KB=100    # Maximum content size per URL in KB
GOOGLE_GEMINI_URL_FETCH_TIMEOUT_MS=10000 # Fetch timeout per URL in milliseconds
GOOGLE_GEMINI_URL_ALLOWED_DOMAINS=*     # Allowed domains (* for all, or comma-separated list)
GOOGLE_GEMINI_URL_BLOCKLIST=malicious.com,spam.net # Blocked domains (comma-separated)
GOOGLE_GEMINI_URL_CONVERT_TO_MARKDOWN=true # Convert HTML to markdown
GOOGLE_GEMINI_URL_INCLUDE_METADATA=true # Include URL metadata in context
GOOGLE_GEMINI_URL_ENABLE_CACHING=true   # Enable URL content caching
GOOGLE_GEMINI_URL_USER_AGENT=MCP-Gemini-Server/1.0 # Custom User-Agent

# Server Configuration
MCP_CLIENT_ID=gemini-sdk-client  # Optional: Default client ID for MCP connections (defaults to "gemini-sdk-client")
MCP_TRANSPORT=stdio  # Options: stdio, sse, streamable, http (replaced deprecated MCP_TRANSPORT_TYPE)
MCP_LOG_LEVEL=info   # Optional: Log level for MCP operations (debug, info, warn, error)
MCP_ENABLE_STREAMING=true # Enable SSE streaming for HTTP transport
MCP_SESSION_TIMEOUT=3600  # Session timeout in seconds for HTTP transport
SESSION_STORE_TYPE=memory  # Options: memory, sqlite
SQLITE_DB_PATH=./data/sessions.db  # Path to SQLite database file when using sqlite store
ENABLE_HEALTH_CHECK=true
HEALTH_CHECK_PORT=3000

# GitHub Integration
GITHUB_API_TOKEN=your_github_token_here

安全注意事项

此服务实现了多项安全措施，以防范常见漏洞。在生产环境中部署时，了解这些安全功能至关重要。

文件系统安全

路径验证与隔离
- ALLOWED_OUTPUT_PATHS：一项关键安全功能，用于限制文件写入工具可以写入文件的位置
- 安全原则：文件只能在明确允许的目录中创建、读取或修改
- 生产环境要求：始终使用绝对路径，以防止潜在的目录遍历攻击
路径遍历防护
- FileSecurityService 通过以下方式实现强大的路径遍历防护：
  - 将路径完全解析为绝对路径
  - 规范化路径，妥善处理 ".." 和 "." 片段
  - 验证规范化后的路径仍位于允许的目录中
  - 同时检查基于字符串的前缀和相对路径计算，以提供冗余安全保障
符号链接安全
- 完全解析符号链接，并检查其是否位于允许的目录中
- 验证符号链接本身及其目标
- 逐级检查父目录中的符号链接，以防止绕过
- 在验证前完全解析多级符号链接链

身份验证与授权

连接令牌
- MCP_CONNECTION_TOKEN 为连接到此服务的客户端提供基本身份验证
- 应将其视为机密信息，并在生产环境中使用强度高且唯一的值
API 密钥安全
- GOOGLE_GEMINI_API_KEY 可授予对 Google Gemini API 服务的访问权限
- 必须妥善保管，绝不能暴露在客户端代码或日志中
- 使用环境变量或安全的密钥管理系统注入此值

URL 上下文安全

多层 URL 验证
- 协议验证：仅允许使用 HTTP/HTTPS 协议
- 私有网络保护：阻止访问 localhost、私有 IP 地址范围和内部域名
- 域名控制：支持通配符的可配置允许列表/阻止列表
- 可疑模式检测：识别潜在的路径遍历、危险字符和恶意模式
- IDN 同形异义攻击防护：检测可能造成混淆的 Unicode 域名
速率限制和资源保护
- 按域名限流：默认每个域名每分钟 10 个请求
- 内容大小限制：可配置每个 URL 的最大内容大小（默认 100KB）
- 请求超时控制：防止请求挂起（默认 10 秒）
- 并发请求限制：通过受控的批处理防止过载
内容安全
- 内容类型验证：仅处理基于文本的内容类型
- HTML 清理：移除 script 标签、style 块和危险内容
- 元数据提取：安全解析 HTML 元数据，不执行代码
- 内存保护：截断内容，防止内存耗尽攻击

网络安全

传输选项
- stdio：作为派生的子进程使用时可提供进程隔离
- SSE/HTTP：通过网络公开时，确保采取适当的网络级保护措施
端口配置
- 公开服务端口时，适当配置防火墙规则
- 在生产部署中，考虑使用支持 TLS 终止的反向代理

生产部署建议

文件路径
- 始终为 ALLOWED_OUTPUT_PATHS 使用绝对路径
- 使用应用程序目录之外的路径，防止修改源代码
- 将访问范围限制在具有适当权限的特定用途目录中
- 绝不要包含 "/", "/etc", "/usr", "/bin" 或 "/home" 等敏感系统目录
进程隔离
- 使用权限受限的用户运行服务
- 考虑使用容器化（Docker）以增强隔离
机密管理
- 在生产环境中，使用安全的机密管理解决方案，而不是 .env 文件
- 定期轮换 API 密钥和连接令牌
URL 上下文安全
- 仅在需要时启用 URL 上下文：如果不需要，请设置 GOOGLE_GEMINI_ENABLE_URL_CONTEXT=false
- 使用严格的域名允许列表：避免在生产环境中使用 GOOGLE_GEMINI_URL_ALLOWED_DOMAINS=*
- 配置全面的阻止列表：将已知的恶意域名添加到 GOOGLE_GEMINI_URL_BLOCKLIST
- 设置保守的资源限制：为 GOOGLE_GEMINI_URL_MAX_CONTENT_KB 和 GOOGLE_GEMINI_URL_MAX_COUNT 使用适当的值
- 监控 URL 访问模式：查看日志，检查可疑的 URL 访问尝试
- 考虑网络级保护：使用防火墙或代理添加额外的 URL 过滤

错误处理

工具执行失败时，服务会使用 MCP 标准的 McpError 类型进行增强的错误处理。此对象包含：

code：指示错误类型的 ErrorCode 枚举值：
- InvalidParams：参数验证错误（类型错误、缺少必填字段等）
- InvalidRequest：一般请求错误，包括安全拦截和资源未找到
- PermissionDenied：身份验证或授权失败
- ResourceExhausted：速率限制、配额或资源容量问题
- FailedPrecondition：所需条件未满足的操作
- InternalError：意外的服务端或 API 错误
message：包含具体信息、便于用户理解的错误说明。
details：（可选）包含 Gemini SDK 错误的更具体信息的对象。

实现细节

该服务采用多层错误处理方案：

验证层：Zod schema 会在工具层（MCP 请求）和服务层（调用 API 前）验证所有参数。
错误分类：详细的错误映射系统会将 Google GenAI SDK 的错误归类为特定错误类型：
- GeminiValidationError：参数验证失败
- GeminiAuthError：身份验证问题
- GeminiQuotaError：速率限制和配额耗尽
- GeminiContentFilterError：内容安全过滤
- GeminiNetworkError：连接和超时问题
- GeminiModelError：模型相关问题
重试机制：针对暂时性错误，使用指数退避自动重试：
- 自动重试网络问题、超时和速率限制错误
- 可配置重试参数（尝试次数、延迟、退避因子）
- 使用随机抖动防止重试请求同步发起
- 详细记录重试尝试，便于调试

常见错误场景：

身份验证失败： PermissionDenied - API 密钥无效、凭据过期或访问未授权。
参数验证： InvalidParams - 缺少必填字段、数据类型错误或值无效。
安全拦截： InvalidRequest - 内容被安全过滤器拦截，详情会指出 SAFETY 是拦截原因。
未找到文件/缓存： InvalidRequest - 未找到资源，详情会说明缺失的资源。
速率限制： ResourceExhausted - API 配额超出或触发速率限制，详情会说明限制信息。
File API 不可用： FailedPrecondition - 未使用有效的 Google AI Studio 密钥时尝试执行 File API 操作。
路径遍历安全问题： InvalidParams - 尝试访问允许目录之外的音频文件，详情会说明安全验证失败。
图像/音频处理错误：
- InvalidParams - 格式问题、大小限制或输入无效
- InternalError - 分析过程中的处理失败
- ResourceExhausted - 资源密集型操作超出限制

该服务会在错误消息中提供额外上下文，帮助排查问题，包括聊天相关错误的会话 ID，以及参数错误的具体验证详情。

请检查返回的 McpError 中的 message 和 details 字段，获取具体的故障排查信息。

开发与测试

该服务包含一套全面的测试，确保其功能正常并与 Gemini API 兼容。测试分为单元测试（针对单个组件）和集成测试（针对端到端功能）。

测试结构

单元测试：位于 tests/unit/，使用模拟依赖项独立测试各个组件
集成测试：位于 tests/integration/，通过与真实服务交互测试端到端功能
测试工具：位于 tests/utils/，包含用于测试的辅助函数和固定测试数据

运行测试

# Install dependencies first
npm install

# Run all tests
npm run test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Run a specific test file
node --test --loader ts-node/esm tests/path/to/test-file.test.ts

测试方法

服务模拟：测试结合使用直接替换方法和模拟接口来模拟 Gemini API 的响应。这对于对象结构复杂的 @google/genai SDK（v0.10.0）尤其重要。
环境变量：测试会自动检查所需的环境变量；如果缺少 API 密钥，则会跳过需要这些密钥的测试。这样无需凭据也能测试核心功能。
测试服务器：集成测试使用测试服务器固件，该固件会创建一个独立的 HTTP 服务器实例，并配置用于测试的 MCP 处理程序。
RetryService：对重试机制进行了广泛测试，以确保正确处理临时错误，并支持指数退避、抖动和可配置的重试参数。
图像生成：测试专门覆盖与 Gemini API 进行图像生成时的复杂交互，同时支持 Gemini 模型和专用的 Imagen 3.1 模型。

测试环境设置

对于需要访问 API 的测试，请在项目根目录中创建一个 .env.test 文件，并填入以下变量：

# Required for basic API tests
GOOGLE_GEMINI_API_KEY=your_api_key_here

# Required for router tests
GOOGLE_GEMINI_MODEL=gemini-1.5-flash

测试套件会自动检测可用的环境变量，并跳过缺少配置所需的测试。

贡献

欢迎为改进 MCP Gemini Server 做出贡献！本节介绍了参与项目贡献的指南。

开发环境设置

Fork 并克隆代码库

git clone https://github.com/yourusername/mcp-gemini-server.git
cd mcp-gemini-server

安装依赖项
```
npm install
```
设置环境变量 按照“环境变量”一节中的说明，在项目根目录创建一个 .env 文件并填入所需变量。
构建并运行
```
npm run build
npm run dev
```

开发流程

创建功能分支

git checkout -b feature/your-feature-name

进行更改 按照代码风格指南实现功能或修复问题。
编写测试 为所做更改添加测试，以确保功能正常并防止回归。

运行测试和代码检查

npm run test
npm run lint
npm run format

提交更改 使用清晰且描述性强的提交消息，说明更改的目的。

测试指南

为所有新功能编写单元测试
修改功能时更新现有测试
提交拉取请求前确保所有测试均通过
包含正向和负向测试用例
模拟外部依赖项，确保测试无需外部服务即可运行

拉取请求流程

更新文档 更新 README.md 和其他文档，以反映所做更改。
提交拉取请求
- 清楚描述所做更改
- 链接相关问题
- 说明如何测试这些更改
- 确保所有 CI 检查均通过
代码审查
- 处理审查者提出的反馈
- 根据要求进行更改并更新 PR

编码规范

遵循现有代码风格（类／接口／类型使用 PascalCase，函数／变量使用 camelCase）
使用 TypeScript 接口进行强类型定义
使用 JSDoc 注释记录公共 API
通过扩展基础错误类妥善处理错误
遵循基于服务的架构，并使用依赖注入
使用 Zod 进行模式验证
按照项目的 ESLint 和 Prettier 配置格式化代码

代码审查工具

MCP Gemini Server 提供了强大的代码审查功能，利用 Gemini 模型分析 git 差异和 GitHub 代码库。这些工具有助于发现潜在问题、提出改进建议，并针对代码更改提供全面反馈。

本地 Git 差异审查

直接通过命令行审查本地 Git 更改：

# Using the included CLI script
./scripts/gemini-review.sh

# Options
./scripts/gemini-review.sh --focus=security --reasoning=high

CLI 脚本支持多种选项：

--focus=FOCUS：审查重点（安全性、性能、架构、缺陷、通用）
--model=MODEL：使用的模型（默认使用 gemini-flash-2.0，以提高成本效益）
--reasoning=LEVEL：推理力度（无、低、中、高）
--exclude=PATTERN：使用 glob 模式排除文件

GitHub 仓库审查

使用以下工具审查 GitHub 仓库、分支和拉取请求：

GitHub PR Review Tool：分析拉取请求中的问题并提出改进建议
GitHub Repository Review Tool：分析整个仓库或分支

成本优化

默认情况下，代码审查工具使用成本更低的 gemini-flash-2.0 模型。对于大多数代码审查任务，该模型在成本和能力之间取得了良好平衡。对于特别复杂的代码库，或需要更深入推理时，可以指定更强大的模型：

# Using a more powerful model for complex code
./scripts/gemini-review.sh --model=gemini-1.5-pro --reasoning=high

运行测试

GitHub 代码审查功能的测试也可以使用成本更低的模型：

# Run tests with the default gemini-flash-2.0 model
npm run test:unit

服务端功能

健康检查端点

服务端提供内置的健康检查 HTTP 端点，可用于监控和状态检查。此端点独立于 MCP 服务传输，并以轻量级 HTTP 服务的形式运行。

启用后，可通过以下地址访问健康检查：

http://localhost:3000/health

健康检查端点会返回包含以下信息的 JSON 响应：

{
  "status": "running",
  "uptime": 1234,  // Seconds since the server started
  "transport": "StdioServerTransport",  // Current transport type
  "version": "0.1.0"  // Server version
}

可以使用 curl 检查健康端点：

curl http://localhost:3000/health

可通过以下环境变量配置健康检查：

ENABLE_HEALTH_CHECK：设为 "false" 可禁用健康检查服务（默认值："true"）
HEALTH_CHECK_PORT：健康检查服务的端口号（默认值：3000）

会话持久化

服务端支持为 HTTP/SSE 传输持久化存储会话，使会话能够在服务端重启后继续存在，并支持水平扩展。

存储后端

内存存储（默认）
- 会话存储在服务端内存中
- 开发环境下性能出色
- 服务端重启后会话会丢失
- 无需外部依赖
SQLite 存储
- 会话持久化到本地 SQLite 数据库
- 服务端重启后仍然保留
- 自动清理过期会话
- 适用于单实例生产部署

配置

启用 SQLite 会话持久化：

export SESSION_STORE_TYPE=sqlite
export SQLITE_DB_PATH=./data/sessions.db  # Optional, this is the default

SQLite 数据库文件和目录会在首次使用时自动创建。该数据库包含：

自动建立索引以提升性能
内置过期会话清理功能
确保数据完整性的 ACID 合规性

会话生命周期

客户端通过 HTTP/SSE 传输连接时会创建会话
每个会话都有可配置的超时时间（默认值：1 小时）
每次活动都会延长会话过期时间
每分钟自动清理过期会话

优雅关闭

服务端为 SIGTERM 和 SIGINT 信号实现了优雅关闭处理。服务端收到关闭信号时：

尝试妥善断开 MCP 服务传输
如果健康检查服务正在运行，则将其关闭
记录关闭状态
以适当的退出代码退出（成功关闭时为 0，发生错误时为 1）

这样可确保服务端在容器化环境中运行或手动停止时能够干净地终止。

已知问题

分页问题： 由于遍历 SDK 的 Pager 对象存在限制，gemini_listCaches 可能无法可靠地返回 nextPageToken。虽然已实现变通方案，但其可靠性有限。
路径要求： 从服务端环境运行音频转录操作时，必须使用绝对路径。不支持相对路径。
文件大小限制： 用于转录的音频文件大小不得超过 20MB（原始文件大小，即 Base64 编码前的大小）。服务端会读取文件并在内部将其转换为 Base64。较大的文件将被拒绝，并显示错误消息。
API 兼容性： 缓存 API 不支持 Vertex AI 凭据，仅支持 Google AI Studio API 密钥。
模型支持： 此服务主要针对最新的 Gemini 1.5 和 2.5 模型进行测试和优化。虽然其他模型应该也能正常使用，但测试和功能兼容性的重点是这些模型。
TypeScript 构建问题： TypeScript 构建可能会报错，且错误主要出现在测试文件中。这些是类型兼容性问题，不会影响运行时功能。即使存在这些构建警告，服务本身仍可正常运行。
资源使用：
- 图像处理需要消耗大量资源，尤其是处理高分辨率图像时。建议使用较低的分辨率（512x512），以获得更快的响应。
- 同时生成多张图像会按比例增加资源消耗。
- 音频转录仅支持小于 20MB 的文件（原始文件大小）。服务端会读取磁盘上的文件，并在内部处理 Base64 转换。处理所需的时间和资源可能会因文件大小和音频复杂度而大幅增加。
内容处理：
- Base64 编码的图像会分块传输，以高效处理较大的文件。
- 对不同类型的视觉内容（图表、示意图或文档）的理解效果可能有所不同。
- 音频转录的准确性取决于音频质量、说话人数和背景噪声。
URL 上下文功能：
- URL 上下文默认处于禁用状态，必须通过 GOOGLE_GEMINI_ENABLE_URL_CONTEXT=true 显式启用。
- 不支持由 JavaScript 渲染的内容，仅处理静态 HTML 内容。
- 某些网站可能会阻止自动访问，或要求进行当前不支持的身份验证。
- 内容提取质量可能因网站结构和格式而异。
- 每个域名的速率限制（默认每分钟 10 次请求）可能会影响批量处理场景。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

MCP Gemini Server

关于 MCP Gemini Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

MCP Gemini Server

目录

概述

文件上传与基于 URL 的分析

❌ 不支持：直接上传文件

✅ 完全支持：基于 URL 的多媒体分析

本地内容的替代方案

功能

前置条件

安装与设置

手动安装

配置

可用工具

核心生成

函数调用

有状态聊天

远程文件操作（已移除）

缓存（需要 Google AI Studio 密钥）

图像生成

音频转录（已移除）

URL 内容分析

MCP 客户端工具

使用示例

基于 URL 的图像分析示例

YouTube 视频分析示例

支持的多媒体分析用例

图像分析用例

视频分析用例

集成能力

mcp-gemini-server 与 Gemini SDK 的 MCP 函数调用

使用 mcp-gemini-server 的优势：

何时选择哪种方式：

关于此服务自身 MCP 客户端工具的说明：

环境变量

必需：

生产环境必需（除非 NODE_ENV=test）：

可选 - Gemini API 配置：

可选 - URL 上下文配置：

可选 - 安全配置：

可选 — 服务配置：

可选 — GitHub 集成：

可选 — 旧版服务配置（已弃用）：

安全注意事项

文件系统安全

身份验证与授权

URL 上下文安全

网络安全

生产部署建议

错误处理

实现细节

开发与测试

测试结构

运行测试

测试方法

测试环境设置

贡献

开发环境设置

开发流程

测试指南

拉取请求流程

编码规范

代码审查工具

本地 Git 差异审查

GitHub 仓库审查

成本优化

运行测试

服务端功能

健康检查端点

会话持久化

存储后端

配置

会话生命周期

`mcp-gemini-server` 与 Gemini SDK 的 MCP 函数调用

使用 `mcp-gemini-server` 的优势：