MCP Gemini 服务器
概述
该项目提供了一个专用的 MCP（模型上下文协议）服务器，该服务器封装了@google/genai SDK。它将 Google 的 Gemini 模型功能作为标准 MCP 工具公开，从而允许其他 LLM（例如 Cline）或兼容 MCP 的系统利用 Gemini 的功能作为后端主力。
该服务器旨在通过提供通过 MCP 标准管理的一致的、基于工具的界面来简化与 Gemini 模型的集成。
Related MCP server: MCP Gemini API Server
特征
**核心生成：**标准（
gemini_generateContent）和流式（gemini_generateContentStream）文本生成。**函数调用：**使 Gemini 模型能够请求执行客户端定义的函数（
gemini_functionCall）。**状态聊天：**管理跨多个回合的对话上下文（
gemini_startChat、gemini_sendMessage、gemini_sendFunctionResult）。**文件处理：**使用 Gemini API 上传、列出、检索和删除文件。
**缓存：**创建、列出、检索、更新和删除缓存内容以优化提示。
先决条件
Node.js（v18 或更高版本）
来自Google AI Studio 的API 密钥（ https://aistudio.google.com/app/apikey ）。
重要提示：，在使用 Vertex AI 凭据时不受支持。此服务器目前不支持 Vertex AI 身份验证。
安装和设置
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 Gemini Server：
手动安装
**克隆/放置项目：**确保
mcp-gemini-server项目目录在您的系统上可访问。**安装依赖项：**导航到终端中的项目目录并运行：
npm install**构建项目：**编译 TypeScript 源代码：
npm run build此命令使用 TypeScript 编译器 (
tsc)，并将 JavaScript 文件输出到./dist目录（由tsconfig.json中的outDir指定）。主服务器入口点为dist/server.js。**配置 MCP 客户端：**将服务器配置添加到您的 MCP 客户端设置文件（例如，Cline/VSCode 的
cline_mcp_settings.json或 Claude 桌面应用的claude_desktop_config.json）。将/path/to/mcp-gemini-server替换为您系统上的实际路径，并将YOUR_API_KEY替换为您的 Google AI Studio 密钥。{ "mcpServers": { "gemini-server": { // Or your preferred name "command": "node", "args": ["/path/to/mcp-gemini-server/dist/server.js"], // Path to the compiled server entry point "env": { "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY", "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash" // Optional: Set a default model }, "disabled": false, "autoApprove": [] } // ... other servers } }**重启 MCP 客户端：**重启您的 MCP 客户端应用程序（例如，带有 Cline 扩展的 VS Code、Claude 桌面应用程序）以加载新的服务器配置。MCP 客户端将管理服务器进程的启动和停止。
配置
服务器使用环境变量进行配置，通过 MCP 设置中的env对象传递：
GOOGLE_GEMINI_API_KEY（必需）：您从 Google AI Studio 获取的 API 密钥。GOOGLE_GEMINI_MODEL（可选）：指定默认的 Gemini 模型名称（例如gemini-1.5-flash、gemini-1.0-pro）。设置后，当工具调用中省略了modelName参数时，需要模型名称的工具（例如gemini_generateContent、gemini_startChat等）将使用此默认值。当主要使用单个模型时，这可以简化客户端调用。如果未设置此环境变量，则这些工具将需要modelName参数。有关可用的模型名称，请参阅Google AI 文档。
可用工具
此服务器提供以下 MCP 工具。参数模式使用 Zod 定义，用于验证和描述。
**关于可选参数的说明：**许多工具接受复杂的可选参数（例如generationConfig 、 safetySettings 、 toolConfig 、 history 、 functionDeclarations 、 contents ）。这些参数通常是对象或数组，其结构与底层@google/genai SDK 中定义的类型一致。有关这些复杂参数的具体结构和可用字段，请参阅：1. 本项目中对应的src/tools/*Params.ts文件。2. 官方Google AI JS SDK 文档。
核心生成
gemini_generateContent*描述：*根据提示生成非流式文本内容。
必需参数：
prompt（字符串）可选参数：
modelName（字符串）、generationConfig（对象）、safetySettings（数组）
gemini_generateContentStream*描述：*通过流式传输生成文本内容。（注意：当前实现使用了一种变通方法，在返回全文之前会收集所有块。）
必需参数：
prompt（字符串）可选参数：
modelName（字符串）、generationConfig（对象）、safetySettings（数组）
函数调用
gemini_functionCall*描述：*向模型发送提示和函数声明，返回文本响应或请求的函数调用对象（作为 JSON 字符串）。
必需参数：
prompt（字符串）、functionDeclarations（数组）可选参数：
modelName（字符串）、generationConfig（对象）、safetySettings（数组）、toolConfig（对象）
状态聊天
gemini_startChat*描述：启动一个新的有状态聊天会话并返回唯一的必需参数：*无
可选参数：
modelName（字符串）、history（数组）、tools（数组）、generationConfig（对象）、safetySettings（数组）
gemini_sendMessage描述：
sessionId（字符串）、message（字符串）可选参数：
generationConfig（对象）、safetySettings（数组）、tools（数组）、toolConfig（对象）
gemini_sendFunctionResult描述：
sessionId（字符串）、functionResponses（数组）可选参数：
generationConfig（对象）、safetySettings（数组）
文件处理（需要 Google AI Studio 密钥）
gemini_uploadFile描述： 可选参数：
displayName（字符串）、mimeType（字符串）
gemini_listFiles*描述：列出之前上传的文件。\n *必需参数：*无
可选参数：
pageSize（数字）、pageToken（字符串 - 注意：pageToken目前可能无法可靠地返回）。
gemini_getFile描述：
fileName（字符串 - 例如，files/abc123xyz）
gemini_deleteFile描述：
fileName（字符串 - 例如，files/abc123xyz）
缓存（需要 Google AI Studio 密钥）
gemini_createCache描述：
contents（数组）可选参数：
modelName（字符串）、displayName（字符串）、systemInstruction（对象）、ttl（字符串 - 例如“3600s”）
gemini_listCaches*描述：列出现有的缓存内容。\n *必需参数：*无
可选参数：
pageSize（数字）、pageToken（字符串 - 注意：pageToken目前可能无法可靠地返回）。
gemini_getCache描述：
cacheName（字符串 - 例如，cachedContents/abc123xyz）
gemini_updateCache描述：
cacheName（字符串）可选参数：
ttl（字符串）、displayName（字符串）
gemini_deleteCache描述：
cacheName（字符串 - 例如，cachedContents/abc123xyz）
使用示例
以下是 MCP 客户端（如 Cline）如何使用use_mcp_tool格式调用这些工具的示例：
示例 1：简单内容生成（使用默认模型）
示例 2：内容生成（指定模型和配置）
示例 3：开始和继续聊天
开始聊天：
（假设响应包含
发送消息：
示例 4：上传文件
错误处理
当工具执行失败时，服务器会使用 MCP 标准McpError类型返回结构化错误。此对象通常包含：
code：指示错误类型的ErrorCode枚举值（例如，InvalidParams、InternalError、PermissionDenied、NotFound）。message：错误的人类可读描述。details：（可选）一个对象，可能包含来自底层 Gemini SDK 错误的更多具体信息（如安全阻止原因或 API 错误消息），以便进行故障排除。
常见错误场景：
**无效的 API 密钥：**通常会导致
InternalError，其详细信息指示身份验证失败。**无效参数：**导致
InvalidParams（例如，缺少必填字段、错误的数据类型）。**安全阻塞：**可能导致
InternalError错误，详细信息表明SAFETY是阻塞原因或完成原因。**未找到文件/缓存：**可能导致
NotFound或InternalError，具体取决于 SDK 如何显示错误。**速率限制：**可能导致
ResourceExhausted或InternalError。
在排查问题时，请查看返回的McpError的message和details字段来寻找具体的线索。
发展
此服务器遵循项目.clinerules和内部文档中概述的标准 MCP 服务器结构。关键模式包括：
**服务层（
src/services）：**封装与@google/genaiSDK 的交互，使其与 MCP 细节分离。**工具层（
src/tools）：**将服务层功能适配到 MCP 工具，处理参数映射和错误转换。**Zod Schemas（
src/tools/*Params.ts）：**广泛用于定义工具参数、提供验证以及生成对 LLM 交互至关重要的详细描述。**配置（
src/config）：**通过ConfigurationManager进行集中管理。**类型（
src/types）：**清除 TypeScript 定义。
已知问题
gemini_generateContentStream使用了一种变通方法，在返回全文之前收集所有块。真正的流式传输到 MCP 客户端尚未实现。由于迭代 SDK 的 Pager 对象的限制，
gemini_listFiles和gemini_listCaches可能无法可靠地返回nextPageToken。从服务器环境运行时，
gemini_uploadFile需要绝对文件路径。Vertex AI 不支持文件处理和缓存 API，仅支持 Google AI Studio API 密钥。