gemini-mcp-rs

中文文档

A high-performance Rust implementation of MCP (Model Context Protocol) server that wraps the Gemini CLI for AI-driven tasks.

Quick Start

The easiest way to use gemini-mcp-rs is via npx - no manual installation required:

npx @missdeer/gemini-mcp-rs

This command automatically installs the correct binary for your platform and runs it. To add it to Claude Code:

claude mcp add gemini-rs -s user --transport stdio -- npx @missdeer/gemini-mcp-rs

That's it! The MCP server is now available in Claude Code.

Features

• MCP Protocol Support: Implements the official Model Context Protocol using the Rust SDK
• Gemini Integration: Wraps the Gemini CLI to enable AI-driven tasks through MCP
• Session Management: Supports multi-turn conversations via session IDs
• Sandbox Safety: Configurable sandbox mode for isolated execution
• Async Runtime: Built on Tokio for efficient async I/O
• Cross-platform: Works on Windows, Linux, and macOS (x64 and arm64)

Prerequisites

• Rust 1.77.2+ (required for Windows batch file security fix, see CVE-2024-24576)
• Gemini CLI installed and configured
• Claude Code or another MCP client

Building

# Debug build
cargo build

# Release build
cargo build --release

Running

The server communicates via stdio transport:

cargo run

Or after building:

./target/release/gemini-mcp-rs

Command-Line Options

# Display help information
./target/release/gemini-mcp-rs --help

# Display version information
./target/release/gemini-mcp-rs --version

The --help flag provides comprehensive documentation including:

• Environment variables
• MCP client configuration examples
• All supported tool parameters
• GEMINI.md configuration file support
• Return structure format
• Best practices and security information

Installation

Option 1: NPX (Recommended)

Run directly using npx:

npx @missdeer/gemini-mcp-rs

npx handles everything automatically:

1. Installs the platform-specific binary package
2. Launches the MCP server on stdio transport

Or install globally:

npm install -g @missdeer/gemini-mcp-rs

Then add to your Claude MCP configuration:

claude mcp add gemini-rs -s user --transport stdio -- npx @missdeer/gemini-mcp-rs

Option 2: Quick Install (Linux/macOS)

Install the latest release with a single command:

curl -sSL https://raw.githubusercontent.com/missdeer/gemini-mcp-rs/master/scripts/install.sh | bash

Or install a specific version:

curl -sSL https://raw.githubusercontent.com/missdeer/gemini-mcp-rs/master/scripts/install.sh | bash -s v0.1.0

This script will:

• Detect your platform and architecture
• Download the appropriate binary from GitHub releases
• Install it to ~/.local/bin (or /usr/local/bin if needed)
• Automatically add it to your Claude MCP configuration

Option 3: Build from Source

git clone https://github.com/missdeer/gemini-mcp-rs.git
cd gemini-mcp-rs
cargo build --release
claude mcp add gemini-rs -s user --transport stdio -- $(pwd)/target/release/gemini-mcp-rs

Option 4: Install from Release

Download the appropriate binary for your platform from the releases page:

Extract and add to your MCP configuration:

claude mcp add gemini-rs -s user --transport stdio -- /path/to/gemini-mcp-rs

Tool Usage

The server provides a single gemini tool with the following parameters:

Required Parameters

• PROMPT (string): Instruction for the task to send to gemini

Optional Parameters

• sandbox (bool): Run in sandbox mode. Defaults to False
• SESSION_ID (string): Resume the specified session of the gemini. Defaults to empty string, start a new session
• return_all_messages (bool): Return all messages (e.g. reasoning, tool calls, etc.) from the gemini session. Set to False by default, only the agent's final reply message is returned
• model (string): The model to use for the gemini session. If not specified, uses GEMINI_FORCE_MODEL environment variable or the Gemini CLI default
• timeout_secs (int): Timeout in seconds for gemini execution (1-3600). Defaults to GEMINI_DEFAULT_TIMEOUT environment variable or 600 seconds (10 minutes)

Return Structure

Success:

{
  "success": true,
  "SESSION_ID": "session-uuid",
  "agent_messages": "Gemini's reply content..."
}

With return_all_messages enabled:

{
  "success": true,
  "SESSION_ID": "session-uuid",
  "agent_messages": "Gemini's reply content...",
  "all_messages": [...]
}

Failure:

{
  "success": false,
  "error": "Error description"
}

Best Practices

• Always capture and reuse SESSION_ID for multi-turn interactions
• Enable sandbox mode when file modifications should be isolated
• Use return_all_messages only when detailed execution traces are necessary (increases payload size)
• Only pass model when the user has explicitly requested a specific model

Configuration

Environment Variables

• GEMINI_BIN: Override the Gemini CLI binary path. By default, the server uses gemini from your PATH. This is useful for:

  • Using a specific Gemini installation location
  • Testing with a custom binary
  • Development environments with multiple Gemini versions

  Example:

  export GEMINI_BIN=/usr/local/bin/gemini-custom
  cargo run
  

• GEMINI_DEFAULT_TIMEOUT: Default timeout in seconds for gemini execution (1-3600). If not set, defaults to 600 seconds (10 minutes). This can be overridden per-request using the timeout_secs parameter.

  Example:

  export GEMINI_DEFAULT_TIMEOUT=300  # 5 minutes
  cargo run
  

• GEMINI_FORCE_MODEL: Default model to use when no model parameter is provided in the request. This is overridden by explicit model parameters.

  Example:

  export GEMINI_FORCE_MODEL=gemini-2.0-flash
  cargo run
  

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Test with a custom Gemini binary
GEMINI_BIN=/path/to/gemini cargo test

Architecture

The project follows a modular architecture:

• src/main.rs: Entry point that parses CLI arguments and starts the MCP server
• src/lib.rs: Library root that exports modules
• src/server.rs: MCP server implementation and tool handlers
• src/gemini.rs: Gemini CLI execution and result parsing

Contributing

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

License

This project is dual-licensed:

Non-Commercial / Personal Use - GNU General Public License v3.0

Free for personal projects, educational purposes, open source projects, and non-commercial use. See LICENSE for the full GPLv3 license text.

Commercial / Workplace Use - Commercial License Required

If you use gemini-mcp-rs in a commercial environment, workplace, or for any commercial purpose, you must obtain a commercial license.

This includes but is not limited to:

• Using the software at work (any organization)
• Integrating into commercial products or services
• Using for client work or consulting
• Offering as part of a SaaS/cloud service

Contact: missdeer@gmail.com for commercial licensing inquiries.

See LICENSE-COMMERCIAL for more details.

Star History