Content
# Gemini MCP - Intelligent Image Analysis Service Based on Gemini
## Project Overview
Gemini MCP is an MCP (Model Context Protocol) server based on the Google Gemini 2.0 Flash model, specifically designed for image analysis and processing. It can seamlessly integrate into AI assistants that support the MCP protocol, such as Claude Desktop and Cursor, providing powerful visual understanding capabilities.
## Core Features
### 🎯 Main Functions
- **Multimodal Analysis**: Supports image content understanding, scene recognition, text extraction, etc.
- **Flexible Input**: Supports various image input methods, including local file paths, network URLs, and Base64 encoding.
- **Streaming Response**: Outputs analysis results in real-time, enhancing user experience.
- **Intelligent Storage**: Automatically saves processing results and generated images.
### 🚀 Technical Advantages
- **Zero-Dependency Installation**: Supports direct operation with uvx, no prior installation required.
- **Cross-Platform Compatibility**: Supports mainstream operating systems, including macOS, Windows, and Linux.
- **Proxy Support**: Built-in SOCKS5 proxy support, adaptable to various network environments.
- **Standard Protocol**: Fully compliant with the MCP specification, integrable with any MCP client.
## Quick Start
### Method 1: Running with uvx (Recommended)
Run directly without installation:
```bash
# Set API key and start service
GEMINI_API_KEY=your-api-key uvx gemini-mcp
```
### Method 2: Installation via pip
```bash
# Install package
pip install gemini-mcp
# Run service
GEMINI_API_KEY=your-api-key gemini-mcp
```
### Method 3: Running from Source
```bash
# Clone repository
git clone https://github.com/chengfeng2025/gemini-mcp-python.git
cd gemini-mcp-python
# Install dependencies
pip install -r requirements.txt
# Run service
python -m gemini_mcp
```
## Client Configuration
### Claude Desktop Configuration
1. Open configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the following configuration:
```json
{
"mcpServers": {
"gemini": {
"command": "uvx",
"args": ["gemini-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
### Cursor Configuration
Edit `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"gemini": {
"command": "uvx",
"args": ["gemini-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
## Usage Examples
In the configured Claude Desktop or Cursor, you can:
```
# Analyze local image
Please analyze this image: /Users/name/Pictures/photo.jpg
# Analyze online image
Describe the content of this image: https://example.com/image.png
# Extract text from image
Extract all text from the image: /path/to/document.png
# Scene understanding
What scene is this image taken in? /path/to/scene.jpg
```
## Advanced Configuration
### Environment Variables
| Variable Name | Description | Default Value |
|--------------|-------------|---------------|
| `GEMINI_API_KEY` | Gemini API key (required) | - |
| `OUTPUT_DIR` | Output file save directory | `./outputs` |
| `ALL_PROXY` | SOCKS5 proxy address | - |
| `LOG_LEVEL` | Log level | `INFO` |
### Command-Line Parameters
```bash
# View available parameters
gemini-mcp --help
# Run in HTTP service mode
gemini-mcp --mode http --port 8080
# Enable debug mode
gemini-mcp --debug
# Specify output directory
gemini-mcp --output-dir /custom/path
```
## API Reference
### Supported Tools
#### `analyze_image`
Analyze image content and return description.
**Parameters:**
- `image_input`: Image input (file path, URL, or Base64)
- `prompt`: Analysis prompt (optional)
**Example:**
```python
{
"tool": "analyze_image",
"arguments": {
"image_input": "/path/to/image.jpg",
"prompt": "Describe the main content of this image"
}
}
```
## Development Guide
### Local Development
```bash
# Clone project
git clone https://github.com/chengfeng2025/gemini-mcp-python.git
cd gemini-mcp-python
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
```
### Contributing
1. Fork project
2. Create feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Create Pull Request
## Troubleshooting
### Frequently Asked Questions
**Q: "API key not found" prompt**
A: Ensure `GEMINI_API_KEY` environment variable is correctly set.
**Q: Connection timeout error**
A: Check network connection or configure proxy:
```bash
ALL_PROXY=socks5://127.0.0.1:1080 gemini-mcp
```
**Q: Claude Desktop cannot recognize service**
A: Restart Claude Desktop application to reload configuration.
## Project Information
- **Author**: chengfeng2025
- **License**: MIT
- **Version**: 1.0.0
- **Update Time**: January 2025
- **GitHub**: [gemini-mcp-python](https://github.com/chengfeng2025/gemini-mcp-python)
## Related Links
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Gemini API Documentation](https://ai.google.dev/gemini-api/docs)
- [Issue Feedback](https://github.com/chengfeng2025/gemini-mcp-python/issues)
## License
This project is licensed under the MIT License. See [LICENSE](LICENSE) file for details.
---
**Note**: Using this project requires a valid Gemini API key.
### API Key Acquisition
1. **Official Channel**: Visit [Google AI Studio](https://makersuite.google.com/app/apikey) to obtain an official key (requires internet access)
2. **Tuzi API**: Visit [Tuzi API Recharge Platform](https://api.tu-zi.com/topup) to purchase compatible API services (domestic direct connection, no proxy required, fully compatible with Gemini official API interface)
