geminimcp/docs/README_EN.md

Seamless Integration Between Claude Code and Gemini CLI

⭐ Star us on GitHub! Your support means the world to us! 🙏😊

English | 简体中文

---

1. Overview

Gemini-MCP is an MCP server that wraps Google's Gemini CLI tool as a standard MCP protocol interface, enabling Claude Code to invoke Gemini for AI-assisted programming tasks.

🍟 This project provides carefully crafted prompts centered around Gemini's exceptional frontend design capabilities to enrich your use cases. We highly recommend configuring them!

---

2. Quick Start

0. Prerequisites

• Installed and configured Claude Code
• Installed and configured Gemini CLI
• Installed uv tool

Installing uv:

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Note: Windows users are strongly recommended to run this project in WSL!

1. Installation Steps

1.1 Install GeminiMCP

claude mcp add gemini -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/geminimcp.git geminimcp

1.2 Verify Installation

claude mcp list

If you see gemini: ... - ✓ Connected, the installation was successful

1.3 Optional: Configure Auto-Allow

Add mcp__gemini__gemini to the allow list in ~/.claude/settings.json

2. Configure Claude Code Prompts (Optional)

To enable optimal collaboration between Claude Code and Gemini, we strongly recommend adding the following content to ~/.claude/CLAUDE.md

Click to view prompt

## Core Instruction for Gemini MCP

At any point, you must consider how the current process can collaborate with Gemini and how to invoke the Gemini MCP tools as a guarantee for your **objective and comprehensive analysis**.

You **must execute** the following steps:

**1** After you **form an initial analysis** of the user's requirements:
(1) First, inform Gemini of the user's **original requirements (verbatim, no paraphrasing)** and your initial approach;
(2) Engage in **thorough discussion and debate** with Gemini to refine requirement analysis and implementation plans. This step concludes only when you have **ensured a thorough understanding of user requirements and generated a practical action plan**.

**2** Before implementing specific coding tasks, you **must request a code implementation prototype from Gemini** (require Gemini to provide only unified diff patches, strictly prohibit any actual code modifications). After obtaining the code prototype, you **may only use it as a logical reference, then rewrite the code modifications** to create production-grade, highly readable, and maintainable code before implementing the actual programming modifications.
  - **Note:** Gemini excels at frontend code and is proficient in styling and UI component design. When working with frontend code, you must request code prototypes from it (CSS/React/Vue/HTML and other frontend code). At all times, you **must use Gemini's frontend design (prototype code) as the foundation for final frontend code**.
  - For example, when you identify that a user has provided frontend design requirements, your first action must automatically shift to forwarding the user's requirements verbatim to Gemini and having it produce code examples (strictly prohibit any modifications or abbreviations to user requirements at this stage). That is, you must obtain the code foundation from Gemini before proceeding with any subsequent actions.

## Gemini Tool Invocation Specification

1. Tool Overview

  Gemini MCP provides a tool called `gemini` for invoking Google Gemini models to execute AI tasks. This tool possesses exceptional frontend aesthetics, task planning, and requirement understanding capabilities, but has limitations in **context length (Effective 32k)**.

2. Usage and Specifications

  **Mandatory Restrictions**:
  - **Session Management**: Capture the returned `SESSION_ID` for multi-turn conversations.
  - **Backend Avoidance**: Strictly prohibit Gemini from writing complex backend business logic code.

  **Optimal Scenarios (Must Prioritize Gemini Invocation)**:
  - **Requirement Clarification**: Assist in generating guiding questions during the task initiation phase.
  - **Task Planning**: Generate step-by-step implementation plans.
  - **Frontend Prototypes**: Write CSS, HTML, UI component code, and adjust styling.

---

3. Tool Documentation

Click to view gemini tool details

gemini Tool

Parameter	Type	Required	Default	Description
PROMPT	str	✅	-	Task instructions sent to Gemini
sandbox	bool	❌	False	Enable sandbox mode
SESSION_ID	str	❌	""	Session ID (empty for new session)
return_all_messages	bool	❌	False	Return complete message history
model	str	❌	""	Specify model (defaults to Gemini CLI config)

Return Value Structure

On Success:

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

When return_all_messages is enabled, additionally includes:

{
  "all_messages": [...]
}

On Failure:

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

---

4. FAQ

Q1: What's the difference from using Gemini CLI directly?

GeminiMCP wraps Gemini CLI as an MCP protocol, enabling programmatic invocation by Claude Code with support for session management and structured returns.

Q2: Will sessions conflict?

No. Each session uses an independent SESSION_ID, ensuring complete isolation.

---

🤝 Contributing

# Clone repository
git clone https://github.com/GuDaStudio/geminimcp.git
cd geminimcp

# Install dependencies
uv sync

---

📄 License

This project is licensed under the MIT License.

Copyright (c) 2025 guda.studio

---

Power this project with a 🌟~