Gemini MCP - 基于 Gemini 的智能图像分析服务
项目概述
Gemini MCP 是一个基于 Google Gemini 2.0 Flash 模型的 MCP（Model Context Protocol）服务器，专门用于图像分析和处理。它可以无缝集成到 Claude Desktop、Cursor 等支持 MCP 协议的 AI 助手中，提供强大的视觉理解能力。
核心特性
🎯 主要功能
- 多模态分析：支持图片内容理解、场景识别、文字提取等
- 灵活输入：支持本地文件路径、网络 URL、Base64 编码等多种图片输入方式
- 流式响应：实时流式输出分析结果，提升用户体验
- 智能存储：自动保存处理结果和生成的图片
🚀 技术优势
- 零依赖安装：支持 uvx 直接运行，无需预先安装
- 跨平台兼容：支持 macOS、Windows、Linux 等主流操作系统
- 代理支持：内置 SOCKS5 代理支持，适应各种网络环境
- 标准协议：完全符合 MCP 规范，可与任何 MCP 客户端集成
快速开始
方式一：使用 uvx 运行（推荐）
无需安装，直接运行：
# 设置 API 密钥并启动服务
GEMINI_API_KEY=your-api-key uvx gemini-mcp
方式二：通过 pip 安装
# 安装包
pip install gemini-mcp
# 运行服务
GEMINI_API_KEY=your-api-key gemini-mcp
方式三：从源码运行
# 克隆仓库
git clone https://github.com/chengfeng2025/gemini-mcp-python.git
cd gemini-mcp-python
# 安装依赖
pip install -r requirements.txt
# 运行服务
python -m gemini_mcp
客户端配置
Claude Desktop 配置
-
打开配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
添加以下配置：
{
"mcpServers": {
"gemini": {
"command": "uvx",
"args": ["gemini-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
Cursor 配置
编辑 ~/.cursor/mcp.json:
{
"mcpServers": {
"gemini": {
"command": "uvx",
"args": ["gemini-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
使用示例
在配置好的 Claude Desktop 或 Cursor 中，你可以：
# 分析本地图片
请分析这张图片：/Users/name/Pictures/photo.jpg
# 分析网络图片
描述一下这个图片的内容：https://example.com/image.png
# 提取图片中的文字
提取图片中的所有文字：/path/to/document.png
# 场景理解
这张图片是在什么场景下拍摄的？/path/to/scene.jpg
高级配置
环境变量
| 变量名 | 说明 | 默认值 |
|---|---|---|
GEMINI_API_KEY | Gemini API 密钥（必需） | - |
OUTPUT_DIR | 输出文件保存目录 | ./outputs |
ALL_PROXY | SOCKS5 代理地址 | - |
LOG_LEVEL | 日志级别 | INFO |
命令行参数
# 查看所有可用参数
gemini-mcp --help
# 以 HTTP 服务模式运行
gemini-mcp --mode http --port 8080
# 启用调试模式
gemini-mcp --debug
# 指定输出目录
gemini-mcp --output-dir /custom/path
API 参考
支持的工具
analyze_image
分析图片内容并返回描述。
参数：
image_input: 图片输入（文件路径、URL 或 Base64）prompt: 分析提示词（可选）
示例：
{
"tool": "analyze_image",
"arguments": {
"image_input": "/path/to/image.jpg",
"prompt": "描述这张图片中的主要内容"
}
}
开发指南
本地开发
# 克隆项目
git clone https://github.com/chengfeng2025/gemini-mcp-python.git
cd gemini-mcp-python
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest tests/
贡献代码
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 创建 Pull Request
故障排除
常见问题
Q: 提示 "API key not found"
A: 确保已正确设置 GEMINI_API_KEY 环境变量。
Q: 连接超时错误 A: 检查网络连接，或配置代理：
ALL_PROXY=socks5://127.0.0.1:1080 gemini-mcp
Q: Claude Desktop 无法识别服务 A: 重启 Claude Desktop 应用以重新加载配置。
项目信息
- 作者: chengfeng2025
- 许可证: MIT
- 版本: 1.0.0
- 更新时间: 2025年1月
- GitHub: gemini-mcp-python
相关链接
许可证
本项目采用 MIT 许可证。详见 LICENSE 文件。
注意：使用本项目需要有效的 Gemini API 密钥。
API 密钥获取方式
- 官方渠道：访问 Google AI Studio 获取官方密钥（需要科学上网）
- 兔子 API：访问 兔子API充值平台 购买兼容官方格式的 API 服务（国内直连，无需梯子，完全兼容 Gemini 官方 API 接口）