MCP 服务器

Gemini MCP Server

一个用于与 Google Gemini API 交互的模型上下文协议 (MCP) 服务器。

vytautas-bunevicius

开发者工具

访问服务器

README

Gemini MCP 服务器

用于与 Google Gemini AI 模型交互的模型上下文协议 (MCP) 服务器。

该服务器实现了模型上下文协议规范，充当桥梁，允许 MCP 客户端（如 Claude for Desktop）通过标准化接口与 Google 强大的 Gemini AI 模型无缝交互。

概述

该服务器充当适配器，将来自 MCP 客户端的请求转换为 Google Gemini 模型的 API 调用，并以 MCP 格式返回响应。它使 MCP 兼容客户端的用户能够利用 Gemini 的功能，包括不同的模型和函数调用。

特性

标准 MCP 实现：完全支持 MCP 规范，包括工具和资源。
本地传输：主要设计用于 stdio 传输，以实现安全、本地连接（例如，与桌面应用程序）。也支持通过 Docker 进行网络传输。
最新的 Gemini API 集成：支持最新的 Gemini 模型，包括 Gemini 1.5 系列（通过 API 提供）。
函数调用支持：为支持它的模型实现 Gemini 的函数调用功能。
弹性：包括重试逻辑和指数退避，用于处理瞬态 API 错误。

可用工具

这些工具在连接到此服务器的 MCP 客户端中可用。

ask_gemini

向指定的 Gemini 模型发送单个问题（提示）并返回响应。

参数：

model (字符串，必需)：要使用的 Gemini 模型 ID（例如，"gemini-1.5-flash-latest"）。
query (字符串，必需)：要发送到 Gemini 模型的问题或提示。
temperature (数字，可选)：控制随机性（0.0 到 1.0）。值越高表示响应越有创意。
maxOutputTokens (整数，可选)：响应中要生成的最大 token 数。
topK (整数，可选)：在每个步骤中要考虑的最高概率 token 的数量。
topP (数字，可选)：要考虑的 token 的累积概率质量（nucleus 采样）。

chat_with_gemini

管理与指定 Gemini 模型的多轮对话。

参数：

model (字符串，必需)：要使用的 Gemini 模型 ID。
conversation (数组，必需)：表示对话历史记录的数组。每个元素应符合预期的格式（例如，{ role: 'user' | 'model', parts: [{ text: '...' }] }）。
message (字符串，必需)：要添加到对话的新用户消息。
temperature (数字，可选)：控制随机性（0.0 到 1.0）。
maxOutputTokens (整数，可选)：要生成的最大 token 数。

gemini_function_call

利用 Gemini 的函数调用功能（仅适用于支持它的模型）。向模型发送提示和一组函数定义，期望它可能返回调用其中一个函数的请求。

参数：

model (字符串，必需)：要使用的 Gemini 模型 ID（必须支持函数调用）。
prompt (字符串，必需)：要发送到模型的提示。
functions (数组，必需)：符合 Gemini API 规范的函数声明数组。
temperature (数字，可选)：控制随机性（0.0 到 1.0）。
maxOutputTokens (整数，可选)：要生成的最大 token 数。

可用资源

这些资源提供可通过 MCP 客户端访问的信息。

gemini_models

提供有关当前可通过配置的 API 密钥访问的 Gemini 模型的详细信息，可能包括功能和上下文窗口大小（受 API 限制）。

支持的 Gemini 模型

该服务器与通过 Google Generative AI SDK 提供的模型进行交互。常见的模型包括（但不限于，请查看 gemini_models 资源以获取当前可用的模型）：

Gemini 1.5:
- gemini-1.5-pro-latest
- gemini-1.5-flash-latest
Gemini 1.0:
- gemini-pro

(注意：模型可用性可能会根据 Google 的 API 更新和您的 API 密钥访问级别而变化。)

安装

先决条件

Node.js：建议使用 18 或更高版本。
npm 或 yarn：Node.js 的包管理器。
Google Gemini API 密钥：从 Google AI Studio 获取一个。 请务必保护此密钥！

设置

克隆存储库：

git clone [https://github.com/vytautas-bunevicius/gemini-mcp-server.git](https://github.com/vytautas-bunevicius/gemini-mcp-server.git)
cd gemini-mcp-server

安装依赖项：

npm install
# or if using yarn:
# yarn install
# Consider using 'npm ci' for reproducible builds in CI/CD environments

配置 API 密钥： 在项目根目录中创建一个 .env 文件并添加您的 API 密钥：
```
# .env
GEMINI_API_KEY=YOUR_API_KEY_HERE
```
重要提示： 如果 .env 尚未在您的 .gitignore 文件中，请将其添加到该文件中，以防止意外提交您的密钥。
构建项目： 这会将 TypeScript 代码编译为 JavaScript。
```
npm run build
```
输出将在 build 目录中。
启动服务器（用于测试或直接使用）： 此命令通常使用 stdio 运行服务器进行通信，适用于配置为直接启动该进程的客户端，如 Claude Desktop。
```
npm start
```

Docker 设置

您也可以在 Docker 容器中运行服务器。

构建 Docker 镜像

从项目根目录：

docker build -t gemini-mcp-server .

运行容器 (Stdio)

这使用 stdio 运行容器进行通信，类似于 npm start。您通常会将 MCP 客户端配置为执行此 Docker 命令。

# Replace YOUR_API_KEY_HERE with your actual key
docker run -i --rm \
  -e GEMINI_API_KEY=YOUR_API_KEY_HERE \
  gemini-mcp-server

(注意：-i 标志对于 stdin 交互至关重要。)

运行容器 (用于 Claude Desktop 的网络端口)

此方法运行容器并公开一个网络端口（例如，3001）。如果配置 Claude Desktop 通过 URL 而不是启动命令进行连接，这将非常有用。

# Replace YOUR_API_KEY_HERE with your actual key
docker run -it --rm \
  -e GEMINI_API_KEY=YOUR_API_KEY_HERE \
  -p 127.0.0.1:3001:3001 \
  --name gemini-mcp \
  gemini-mcp-server

(注意：-p 127.0.0.1:3001:3001 仅将端口绑定到 localhost 以确保安全。)

Docker Compose

为了更轻松的管理，尤其是在与其他服务结合使用时，请使用 Docker Compose。

创建一个 docker-compose.yml 文件：

version: '3.8'
services:
  gemini-mcp:
    build: .
    container_name: gemini-mcp
    environment:
      # It's more secure to use .env files with Docker Compose
      # Create a .env file in the same directory as docker-compose.yml:
      # GEMINI_API_KEY=YOUR_API_KEY_HERE
      - GEMINI_API_KEY=${GEMINI_API_KEY}
    # Uncomment ports section if you need network access (e.g., for Claude URL config)
    # ports:
    #  - "127.0.0.1:3001:3001" # Expose port 3001 only on localhost
    # Use 'stdin_open: true' and 'tty: true' if you need stdio interaction via Compose
    # stdin_open: true # Equivalent to -i
    # tty: true      # Equivalent to -t

在与 docker-compose.yml 相同的目录中创建一个 .env 文件：
```
# .env (for Docker Compose)
GEMINI_API_KEY=YOUR_API_KEY_HERE
```

使用 Docker Compose 运行：

# To run in the foreground (for stdio or debugging)
docker-compose up --build

# To run in the background (detached, usually for network mode)
# docker-compose up -d --build

配置 Claude for Desktop

您需要告诉 Claude for Desktop 如何启动并与此 MCP 服务器通信。

安装 Claude for Desktop：如果您尚未安装，请从 claude.ai/desktop 获取。
找到配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json（路径可能略有不同）
编辑配置文件：添加 mcpServers 部分。选择以下一种方法：

方法 1：使用 Stdio（推荐用于本地使用）

此方法允许 Claude 使用 stdio 直接管理服务器进程。将 /absolute/path/to/gemini-mcp-server/build/index.js 替换为您系统上的实际路径，并提供您的 API 密钥。

{
  "mcpServers": {
    "gemini": {
      "command": "node", // Command to execute
      "args": [
        // **IMPORTANT**: Use the FULL, ABSOLUTE path to the compiled JS file
        "/absolute/path/to/gemini-mcp-server/build/index.js"
      ],
      "env": {
        // Provide the API key directly here
        "GEMINI_API_KEY": "YOUR_API_KEY_HERE"
        // You can add other environment variables if needed
        // "NODE_ENV": "production"
      }
    }
    // You can add other MCP servers here
  }
  // Other Claude settings might be present here
}

方法 2：使用 Docker 网络端口

如果您运行了公开端口 3001 的 Docker 容器（如 Docker 部分所示），则可以配置 Claude 通过 URL 进行连接。确保在启动 Claude 之前运行 Docker 容器。

{
  "mcpServers": {
    "gemini": {
      // Connect to the exposed port from the Docker container
      "url": "http://localhost:3001"
    }
    // You can add other MCP servers here
  }
  // Other Claude settings might be present here
}

保存并重启：保存 claude_desktop_config.json 文件并重启 Claude for Desktop。

从 Claude 使用 Gemini

正确配置并重启 Claude 后：

Claude 应检测到新的 MCP 服务器（在本例中为“gemini”）。
服务器提供的工具（如 ask_gemini、chat_with_gemini）将变为可用。在撰写消息时，在 Claude 的界面中查找工具图标（通常是锤子）。
您可以通过自然地询问 Claude 来调用这些工具：
- "使用 ask_gemini 工具和 gemini-1.5-flash-latest 模型来告诉我关于模型上下文协议的信息。"
- "询问 Gemini Pro：最新的 Gemini 模型的主要特性是什么？"
- "开始与 chat_with_gemini 讨论使用 MCP 的好处。"
- "使用 gemini_models 资源列出可用的模型。"

然后，Claude 将根据您的配置和检测到的工具提示您（或自动使用该工具）。

安全注意事项

API 密钥安全：您的 GEMINI_API_KEY 是敏感的。
- 切勿将您的 .env 文件或 API 密钥直接提交到源代码控制中（确保 .env 在您的 .gitignore 中）。
- 使用环境变量或安全密钥管理解决方案，尤其是在生产或共享环境中。
- 使用 Docker 时，首选安全地注入环境变量（例如，通过 Docker Compose .env 文件或编排密钥），而不是将它们硬编码到 Dockerfile 或命令中。
网络暴露：如果使用暴露的网络端口运行服务器（如 Docker 网络示例中，或者如果您修改了服务器代码），请确保将其绑定到 localhost (127.0.0..1)，除非您特别需要更广泛的网络访问并了解安全影响。如果暴露在 localhost 之外，请考虑防火墙规则。
输入清理：虽然 MCP 协议具有结构，但请注意传递给 Gemini 模型的提示来自用户输入。

许可证

本项目根据 Unlicense 的条款获得许可。这意味着它实际上已发布到公共领域。有关详细信息，请参见 LICENSE 文件。您可以自由地使用、修改和分发代码，几乎没有任何限制。

Gemini MCP Server

README

Gemini MCP 服务器

目录

概述

特性

可用工具

ask_gemini

chat_with_gemini

gemini_function_call

可用资源

gemini_models

支持的 Gemini 模型

安装

先决条件

设置

Docker 设置

构建 Docker 镜像

运行容器 (Stdio)

运行容器 (用于 Claude Desktop 的网络端口)

Docker Compose

配置 Claude for Desktop

方法 1：使用 Stdio（推荐用于本地使用）

方法 2：使用 Docker 网络端口

从 Claude 使用 Gemini

安全注意事项

许可证

推荐服务器