# Gemini MCP Server

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-1.0+-green.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A Model Context Protocol (MCP) server that provides Google Gemini AI capabilities to MCP-compatible clients like Claude Desktop and Claude Code.

## Overview

This MCP server acts as a bridge between MCP clients and Google Gemini models, enabling:

- **Multi-turn conversations** with session management
- **File and image analysis** with glob pattern support
- **Automatic model selection** based on content length
- **Deep thinking mode** with reasoning output
- **Google Search integration** for up-to-date information

## Prerequisites

### 1. AIStudioProxyAPI Backend

This MCP server requires [AIStudioProxyAPI](https://github.com/CJackHwang/AIstudioProxyAPI) as the backend service.

```bash
# Clone and setup AIStudioProxyAPI
git clone https://github.com/CJackHwang/AIstudioProxyAPI.git
cd AIstudioProxyAPI
poetry install
poetry run python launch_camoufox.py --headless
```

The API will be available at `http://127.0.0.1:2048` by default.

### 2. uv Package Manager

```bash
# Install uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Installation

```bash
# Clone this repository
git clone https://github.com/YOUR_USERNAME/aistudio-gemini-mcp.git
cd aistudio-gemini-mcp

# Install dependencies
uv sync
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GEMINI_API_BASE_URL` | `http://127.0.0.1:2048` | AIStudioProxyAPI endpoint |
| `GEMINI_API_KEY` | _(empty)_ | Optional API key |
| `GEMINI_PROJECT_ROOT` | `$PWD` | Root directory for file resolution |

### Claude Desktop / Claude Code

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/aistudio-gemini-mcp", "python", "server.py"],
      "env": {
        "GEMINI_API_BASE_URL": "http://127.0.0.1:2048"
      }
    }
  }
}
```

## Tools

### `gemini_chat`

Send a message to Google Gemini with optional file attachments.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Message to send (1-100,000 chars) |
| `file` | list[string] | No | File paths or glob patterns |
| `session_id` | string | No | Session ID (`"last"` for recent) |
| `model` | string | No | Override model selection |
| `system_prompt` | string | No | System context |
| `temperature` | float | No | Sampling temperature (0.0-2.0) |
| `max_tokens` | int | No | Max response tokens |
| `response_format` | enum | No | `"markdown"` or `"json"` |

**Examples:**

```python
# Simple query
gemini_chat(prompt="Explain quantum computing")

# With file
gemini_chat(prompt="Review this code", file=["main.py"])

# With image
gemini_chat(prompt="Describe this", file=["photo.png"])

# Continue conversation
gemini_chat(prompt="Tell me more", session_id="last")

# Multiple files
gemini_chat(prompt="Analyze", file=["src/**/*.py"])
```

### `gemini_list_models`

List available Gemini models.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter_text` | string | No | Filter models by name |
| `response_format` | enum | No | `"markdown"` or `"json"` |

## Model Selection

Auto-selects model based on content length:

| Content Size | Model |
|-------------|-------|
| ≤ 8,000 chars | `gemini-3-pro-preview` |
| > 8,000 chars | `gemini-2.5-pro` |
| Fallback | `gemini-2.5-flash` |

## Features

### Session Management
- Automatic session creation
- Use `"last"` to continue recent conversation
- LRU eviction (max 50 sessions)

### File Support
- **Images**: PNG, JPG, JPEG, GIF, WebP, BMP
- **Text**: Any text-based file with auto-encoding detection
- **Glob patterns**: `*.py`, `src/**/*.ts`, etc.

### Built-in Capabilities
- `reasoning_effort: high` - Deep thinking mode
- `google_search` - Web search integration
- Automatic retry with model fallback

## Running Standalone

```bash
# Start the MCP server
uv run python server.py
```

## Project Structure

```
aistudio-gemini-mcp/
├── server.py           # MCP server implementation
├── pyproject.toml      # Project configuration
├── uv.lock             # Dependency lock file
├── README.md           # This file
├── LICENSE             # MIT License
└── mcp_config_example.json
```

## Related Projects

- [AIStudioProxyAPI](https://github.com/CJackHwang/AIstudioProxyAPI) - Backend API service (required)
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.