gemini-mcp-server

🚀 Gemini MCP Server for Claude Desktop

Gemini MCP Server for Claude Desktop 是一个模型上下文协议（MCP）服务器，它能让 Claude Desktop 使用 Google 的 Gemini AI 模型来生成图像，为用户提供了便捷的图像生成体验。

🚀 快速开始

本服务器允许 Claude Desktop 使用 Google 的 Gemini AI 模型生成图像。安装并配置完成后，重启 Claude Desktop 即可启用。

✨ 主要特性

• 🌟 直接在 Claude Desktop 中使用 Google 的 Gemini 模型生成图像。
• 🔧 提供简单的设置向导，方便进行配置。
• 🎨 可自定义图像生成参数。
• 🔌 与 Claude Desktop 的 MCP 服务器系统集成。
• 📜 具备详细的日志记录和调试功能。
• 🐳 支持 Docker，便于部署和共享。

📦 安装指南

全局安装（推荐）

npm install -g gemini-mcp-server

# 运行设置向导
npx gemini-mcp-setup

本地安装

# 为服务器创建一个目录
mkdir gemini-mcp-server
cd gemini-mcp-server

# 本地安装
npm install gemini-mcp-server

# 运行设置向导
npx gemini-mcp-setup

Docker 安装

你也可以使用 Docker 运行 Gemini MCP 服务器：

# 构建 Docker 镜像
docker build -t gemini-mcp-server .

# 运行 Docker 容器
docker run -e GEMINI_API_KEY="your-api-key" -e OUTPUT_DIR="/app/output" -v /path/on/host:/app/output gemini-mcp-server

⚙️ 配置说明

设置向导将引导你完成配置过程：

1. 输入你的 Google Gemini API 密钥。
2. 指定保存生成图像的目录。
3. 配置日志记录和模型设置。
4. 自动为 Claude Desktop 创建包装脚本。
5. 更新你的 Claude Desktop 配置。

如果你更喜欢手动设置，请参阅下面的 手动配置 部分。

💻 使用示例

基础用法

安装并配置完成后，重启 Claude Desktop 以启用 Gemini MCP 服务器。然后：

1. 与 Claude 开始对话。
2. 要求 Claude 为你生成图像，例如：
   • "生成一张日落时分的山脉风景图"
   • "创建一张带有飞行汽车的未来城市图片"
   • "制作一幅猫弹钢琴的插画"

Claude 将调用 Gemini API 生成图像，并为你提供保存的图像文件路径。

高级用法

你可以使用额外的参数自定义图像生成：

• 风格：指定风格，如 "写实风格"、"艺术风格"、"简约风格" 等。
• 温度：控制生成的创造性/随机性（0.0 - 1.0）。

示例："以写实风格、温度 0.7 生成一张带有霓虹灯的赛博朋克城市图像"

🔧 手动配置

如果你不想使用设置向导，请按照以下步骤操作：

1. 创建配置文件

创建一个包含你设置的 JSON 配置文件：

{
  "apiKey": "YOUR_GEMINI_API_KEY_HERE",
  "outputDir": "/path/to/your/output/directory",
  "debug": true,
  "modelOptions": {
    "model": "gemini-2.0-flash-exp",
    "temperature": 0.4
  }
}

2. 创建包装脚本

创建一个 bash 脚本来运行服务器：

#!/bin/bash
# 设置环境变量
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"
export OUTPUT_DIR="/path/to/your/output/directory"
export DEBUG="true"

# 执行服务器
exec "$(which node)" "$(npm root -g)/gemini-mcp-server/bin/gemini-mcp-server.js"

使脚本可执行：

chmod +x gemini-mcp-wrapper.sh

3. 更新 Claude Desktop 配置

编辑你的 ~/.config/claude/claude_desktop_config.json 文件，添加 Gemini MCP 服务器：

{
  "mcpServers": {
    "gemini-image": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/path/to/your/gemini-mcp-wrapper.sh"
      ],
      "env": {
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE",
        "DEBUG": "true"
      }
    }
  }
}

🐳 Docker 部署

此 MCP 服务器包含一个 Dockerfile，便于部署和共享。Docker 镜像配置为：

• 使用 Node.js 16 Alpine 作为轻量级基础。
• 安装所有必要的依赖项。
• 在 /app/output 设置默认输出目录。
• 允许通过环境变量进行配置。

构建 Docker 镜像

docker build -t gemini-mcp-server .

使用 Docker 运行

docker run \
  -e GEMINI_API_KEY="your-api-key" \
  -e OUTPUT_DIR="/app/output" \
  -e DEBUG="false" \
  -v /path/on/host:/app/output \
  gemini-mcp-server

Docker 环境变量

运行 Docker 容器时，你可以使用以下环境变量配置服务器：

• GEMINI_API_KEY：你的 Google Gemini API 密钥（必需）
• OUTPUT_DIR：保存生成图像的目录（默认：/app/output）
• DEBUG：启用调试日志记录（默认：false）

与 Claude Desktop 一起使用

当将 Docker 容器与 Claude Desktop 一起使用时，你需要：

1. 确保容器正在运行。
2. 配置 Claude Desktop 以连接到容器化服务器。
3. 将输出目录映射到 Claude 可访问的位置。

📚 详细文档

命令行界面

gemini-mcp-server [options]

选项：

• -k, --api-key <key>：Google Gemini API 密钥
• -o, --output-dir <dir>：保存生成图像的目录
• -d, --debug：启用调试日志记录
• -c, --config <path>：自定义配置文件的路径
• -r, --reset-config：将配置重置为默认值
• -v, --version：显示版本信息

环境变量

• GEMINI_API_KEY：你的 Google Gemini API 密钥
• OUTPUT_DIR：保存生成图像的目录
• DEBUG：启用调试日志记录（true 或 false）
• LOG_LEVEL：设置日志级别（ERROR、WARN、INFO 或 DEBUG）
• GEMINI_LOG_FILE：自定义日志文件路径

配置选项

| 属性 | 详情 | 默认值 | |------|------|---------| | apiKey | Google Gemini API 密钥 | （必需） | | outputDir | 保存生成图像的目录 | ~/Claude/gemini-images | | debug | 启用调试日志记录 | false | | modelOptions.model | 要使用的 Gemini 模型 | gemini-2.0-flash-exp | | modelOptions.temperature | 控制创造性/随机性 | 0.4 | | modelOptions.topK | 前 k 采样参数 | 32 | | modelOptions.topP | 前 p 采样参数 | 1 | | modelOptions.maxOutputTokens | 最大输出令牌数 | 8192 |

🔍 故障排除

常见问题

服务器无法启动或 Claude 无法连接到服务器

1. 检查 ~/Claude/logs/gemini-image-mcp.log 处的日志文件。
2. 验证你的 API 密钥是否正确。
3. 确保所有目录存在并具有适当的权限。
4. 重启 Claude Desktop。

图像未生成

1. 验证你的 Google Gemini API 密钥是否具有正确的权限。
2. 检查输出目录是否存在且可写。
3. 检查日志以获取特定的错误消息。
4. 尝试不同的提示或模型。

错误："Method not found"

这通常意味着 Claude 试图调用 MCP 服务器不支持的方法。检查日志以查看请求的方法。

Docker 特定问题

1. 确保容器具有适当的网络连接。
2. 检查卷挂载是否正确配置。
3. 验证环境变量是否正确设置。
4. 使用 docker logs [container-id] 查看容器日志。

调试模式

启用调试模式以获取更详细的日志：

npx gemini-mcp-server --debug

或者设置环境变量：

export DEBUG=true
npx gemini-mcp-server

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

• Model Context Protocol 提供 MCP 规范。
• Google Generative AI 提供 Gemini API。
• 本项目的所有贡献者。