内容
# Gemini MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io) （MCP）服务器，提供 **23种工具** 用于谷歌的Gemini API -- 聊天，多模态分析，深度研究，文件管理，YouTube 分析等。
使用 [`@google/genai`](https://www.npmjs.com/package/@google/genai) 软件开发工具包（v1.0.0+）构建。
## 功能
- 与Gemini模型聊天（单轮，多轮，带有工具模式）
- 分析图像，音频，视频，PDF，YouTube视频和网址
- 文件API，自动切换：内联小文件（<20MB），上传大文件（高达2GB）
- 带有后台轮询和推送通知的深度研究代理（Termux）
- 结构化JSON输出，嵌入，代码执行，翻译，摘要
- Google搜索基础和网址上下文
- 默认启用思考模式（预算：65535个代币）
- 默认高媒体分辨率
## 先决条件
- **Node.js 18+**
- 一个 [Gemini API 密钥](https://aistudio.google.com/apikey)
## 快速安装
```bash
git clone https://github.com/salviz/gemini-mcp-server.git
cd gemini-mcp-server
npm install
```
### 使用Claude Code注册
命令行界面：
```bash
claude mcp add gemini -- node /path/to/gemini-mcp-server/index.js
```
或添加到您的MCP配置（`~/.claude/claude_desktop_config.json` 或 `.mcp.json`）：
```json
{
"mcpServers": {
"gemini": {
"type": "stdio",
"command": "node",
"args": ["/path/to/gemini-mcp-server/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
## 环境变量
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `GEMINI_API_KEY` | 是 | 您的谷歌Gemini API密钥 |
## 工具（23）
### 聊天和生成（6）
| 工具 | 描述 |
| --- | --- |
| `gemini_chat` | 发送一个提示，可选的搜索基础和网址上下文 |
| `gemini_chat_multi` | 多轮对话，带有消息历史记录 |
| `gemini_chat_with_tools` | 聊天时模式切换：`search`，`code` 或 `all` |
| `gemini_search_grounded` | 基于搜索的生成，带有来源引用 |
| `gemini_structured_output` | 生成匹配提供模式的JSON输出 |
| `gemini_url_context` | 使用Gemini的网址上下文工具分析一个或多个网址 |
### 多模态分析（6）
| 工具 | 描述 |
| --- | --- |
| `gemini_analyze_image` | 分析图像文件，支持Gemini Vision（JPG，PNG，GIF，WebP，BMP，SVG） |
| `gemini_analyze_audio` | 转录，摘要或描述音频（MP3，WAV，OGG，FLAC，AAC，M4A，Opus） |
| `gemini_analyze_video` | 分析视频文件；自动通过文件API上传大文件（MP4，AVI，MOV，MKV，WebM） |
| `gemini_analyze_pdf` | 分析PDF文档（通过文件API支持高达2GB） |
| `gemini_analyze_youtube` | 通过网址分析公共YouTube视频（无需下载） |
| `gemini_analyze_url` | 分析来自HTTP/HTTPS网址或GCS URI（`gs://`）的内容 |
### 深度研究（2）
| 工具 | 描述 |
| --- | --- |
| `gemini_deep_research` | 启动深度研究任务；完成时发送推送通知 |
| `gemini_check_research` | 通过交互ID检查正在运行的深度研究任务的状态 |
### 文件API（3）
| 工具 | 描述 |
| --- | --- |
| `gemini_upload_file` | 上传文件到Gemini（高达2GB，保留48小时） |
| `gemini_list_files` | 列出所有上传的文件，带有元数据 |
| `gemini_delete_file` | 通过名称删除上传的文件 |
### 实用工具（6）
| 工具 | 描述 |
| --- | --- |
| `gemini_list_models` | 列出可用的Gemini模型，带有功能和代币限制 |
| `gemini_count_tokens` | 使用模型的标记器计算文本中的代币 |
| `gemini_embed` | 生成文本嵌入（默认：`gemini-embedding-001`，3072维度） |
| `gemini_code_execute` | 通过Gemini的内置沙箱执行Python代码 |
| `gemini_summarize` | 总结文本，带有可配置的样式（简洁，详细，项目符号） |
| `gemini_translate` | 将文本翻译成任何语言，带有可选的模型覆盖 |
## 模型选择
默认模型：**`gemini-3.1-pro-preview`**。每个工具都接受一个可选的`model`参数。
| 模型 | 最适合 |
| --- | --- |
| `gemini-3.1-pro-preview` | 默认。多数任务的最佳质量 |
| `gemini-2.5-flash` | 更快的响应，更低的成本 |
| `gemini-embedding-001` | 文本嵌入（由`gemini_embed`使用） |
| `deep-research-pro-preview-12-2025` | 深度研究代理（内部使用） |
## 文件API和大文件处理
服务器自动处理文件大小：
- **<= 20MB**：作为base64发送（快速，无上传步骤）
- **> 20MB高达2GB**：通过Gemini文件API上传，然后通过URI引用
- **YouTube网址**：直接通过`fileData.fileUri`传递（无需下载）
- **HTTP/HTTPS网址**：通过`createPartFromUri`传递（高达100MB）
- **GCS URI**（`gs://`）：通过`fileData.fileUri`传递
上传的文件保留48小时。使用`gemini_list_files`和`gemini_delete_file`管理它们。
## 深度研究
`gemini_deep_research`工具使用Gemini的交互API，带有`deep-research-pro-preview-12-2025`代理：
1. 在后台模式下启动研究
2. 如果快速完成，则轮询50秒
3. 如果仍在运行，则启动后台轮询（每30秒，最高30分钟）
4. 当完成时，通过`termux-notification`发送**推送通知**
5. 将完整结果保存到`~/.cache/deep_research_*.txt`
使用`gemini_check_research`随时手动轮询。
## 项目结构
```
gemini-mcp-server/
index.js # 服务器入口点
tools/
shared.js # 共享配置，AI客户端，extractText帮助程序
chat.js # 17种工具：聊天，分析，研究，文件，YouTube
utility.js # 6种工具：模型，代币，嵌入，代码，摘要，翻译
package.json
```
## 安全
- **仅从环境获取API密钥** -- 绝不硬编码在源代码中
- **验证文件路径** -- 需要绝对路径，在读取前检查存在性
- **标准输入输出传输** -- 无暴露的网络服务器
- **无日志或存储数据** -- 不保留提示和响应
## 依赖项
| 包 | 版本 | 用途 |
| --- | --- | --- |
| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP服务器框架 |
| `@google/genai` | ^1.0.0 | 谷歌Gemini AI软件开发工具包 |
| `zod` | ^3.24.0 | 输入模式验证 |
## 许可证
MIT
