aistudio-gemini-mcp by xumingjun5208 - MCP Server

Gemini MCP Server

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 as the backend service.

# 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

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

Installation

# 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:

{
  "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:

# 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

# 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 - Backend API service (required)
Model Context Protocol - MCP specification

License

MIT License - see for details.

Contributing

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