MCP 服务器

@staticpayload/gemini-mcp

Bridges Google's Gemini CLI to MCP-compatible AI assistants, enabling prompt execution, model listing, and raw CLI commands.

README

<h1 align="center"> <br> ✦ @staticpayload/gemini-mcp <br> </h1>

<h4 align="center"> Bridge Google's Gemini CLI to any MCP-compatible AI assistant </h4>

<p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-tools">Tools</a> • <a href="#-usage">Usage</a> • <a href="#-configuration">Configuration</a> • <a href="#-autonomous-setup">Autonomous Setup</a> • <a href="#-how-it-works">How It Works</a> </p>

<br>

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Claude / Cursor / Any MCP Client                              │
│                    │                                            │
│                    ▼                                            │
│   ┌─────────────────────────────────────┐                       │
│   │     @staticpayload/gemini-mcp       │                       │
│   │   ┌─────────┐ ┌─────────┐ ┌───────┐ │                       │
│   │   │ prompt  │ │ models  │ │  raw  │ │   ◄── MCP Tools       │
│   │   └────┬────┘ └────┬────┘ └───┬───┘ │                       │
│   └────────┼───────────┼─────────┼──────┘                       │
│            │           │         │                              │
│            └───────────┼─────────┘                              │
│                        ▼                                        │
│            ┌───────────────────────┐                            │
│            │    Gemini CLI         │   ◄── Your existing auth   │
│            │    (gemini binary)    │       & configuration      │
│            └───────────────────────┘                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

</div>

<br>

✨ Features

🔌 Zero Configuration

Uses your existing Gemini CLI installation and authentication. No API keys to manage, no duplicate auth flows.

🚀 Universal Access

</td> <td width="50%">

⚡ Production Ready

Health checks, graceful shutdown, 5-minute timeouts, proper signal handling. Built for reliability.

🛠️ Three Powerful Tools

Prompt execution, model listing, and raw CLI access for advanced use cases.

</td> </tr> </table>

🚀 Quick Start

Prerequisites

# Install Gemini CLI globally
npm install -g @google/gemini-cli

# Authenticate (run once)
gemini

Run the MCP Server

npx @staticpayload/gemini-mcp

That's it. The server starts and waits for MCP connections via stdio.

🔧 Tools

`gemini_prompt`

Send a prompt to Gemini and get a response.

Parameter	Type	Required	Description
`prompt`	string	✅	The prompt to send
`model`	string	❌	Model override (e.g., `gemini-2.5-flash`)

`gemini_models`

List all available Gemini models.

No parameters required.

`gemini_raw`

Execute any Gemini CLI command with raw arguments.

Parameter	Type	Required	Description
`args`	string[]	✅	CLI arguments array

Example: ["--version"] or ["-p", "Hello", "-m", "gemini-2.5-pro"]

📋 Usage

With Claude Desktop

Add to your Claude configuration (~/.claude/config.json):

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["@staticpayload/gemini-mcp"]
    }
  }
}

With Claude CLI

claude mcp add gemini -- npx @staticpayload/gemini-mcp

With Cursor / Windsurf

Add to your MCP settings:

{
  "gemini": {
    "command": "npx",
    "args": ["@staticpayload/gemini-mcp"]
  }
}

⚙️ Configuration

Environment Variables

Variable	Description
`GEMINI_CLI_PATH`	Override the Gemini binary location
`GEMINI_API_KEY`	Gemini API key (if not using OAuth)
`GOOGLE_APPLICATION_CREDENTIALS`	Service account credentials path

Inherited Configuration

The server inherits your full environment, so existing Gemini configuration works automatically:

~/.config/gemini/          ← CLI configuration
~/.gemini/settings.json    ← Gemini settings
GEMINI_* env vars          ← All Gemini environment variables
gcloud auth                ← Application default credentials

🤖 Autonomous Setup

For production deployments with Vertex AI authentication and zero interactive prompts, use the automated setup:

# 1. Copy environment template
cp .env.example .env

# 2. Edit .env with your GCP project
# PROJECT_ID=your-gcp-project-id

# 3. Authenticate with gcloud
gcloud auth application-default login

# 4. Run automated setup
./setup-gemini.sh

# 5. Use Gemini autonomously
./run-gemini.sh

Features:

✅ Vertex AI authentication (no API keys)
✅ No permission prompts for file/shell/web operations
✅ GA/Preview model routing
✅ MCP server integration
✅ Sandbox directory (avoids macOS permission issues)

See GEMINI_SETUP.md for complete documentation.

🔬 How It Works

┌──────────────┐     stdio      ┌─────────────────┐     spawn     ┌─────────────┐
│  MCP Client  │ ◄────────────► │  gemini-cli-mcp │ ◄───────────► │ gemini CLI  │
│  (Claude)    │   JSON-RPC     │    (Node.js)    │   child proc  │  (binary)   │
└──────────────┘                └─────────────────┘               └─────────────┘

MCP Client sends JSON-RPC requests over stdio
gemini-cli-mcp translates MCP tool calls to Gemini CLI commands
Gemini CLI executes with your existing auth & config
Response flows back through the same path

The server is a thin translation layer—all heavy lifting happens in Gemini CLI.

🏗️ Architecture

@staticpayload/gemini-mcp/
├── src/
│   └── index.js      # MCP server (single file, ~300 lines)
├── package.json      # npm package with bin entry
└── README.md

Design Principles:

Single responsibility: translate MCP ↔ Gemini CLI
Zero global state
Fail fast with clear errors
Minimal dependencies (@modelcontextprotocol/sdk, zod)

🐛 Troubleshooting

"Gemini CLI not found"

# Ensure gemini is installed and in PATH
which gemini

# Or set the path explicitly
export GEMINI_CLI_PATH=/path/to/gemini

"Auth method not set"

# Option 1: Run Gemini CLI once to authenticate
gemini

# Option 2: Set API key
export GEMINI_API_KEY=your-api-key

Server not responding

Check stderr output for health check results:

[gemini-mcp] Gemini CLI: /usr/local/bin/gemini (0.22.4)

📄 License

<p align="center"> <sub>Built with lazyness for fun</sub> </p>