Skip to main content
Glama

Gemini CLI MCP Server

A Model Context Protocol (MCP) server that integrates the local gemini CLI tool with Claude Code. This server acts as a bridge, allowing Claude Code to execute Gemini AI queries through the standardized MCP protocol.

Made 99% with Claude Code (including this line).

How It Works

This MCP server provides a simple interface between Claude Code and the Gemini CLI tool:

  1. Claude Code sends a prompt via MCP protocol

  2. The server receives the prompt through stdio JSON-RPC communication

  3. Server executes gemini -p "<prompt>" as a child process

  4. Gemini CLI response is captured and returned to Claude Code

  5. Claude Code displays the result to the user

Claude Code ↔ [JSON-RPC stdio] ↔ MCP Server ↔ [child_process] ↔ gemini CLI

Related MCP server: Gemini MCP Server

Prerequisites

  • Node.js v18+ installed

  • Gemini CLI tool installed and available in your PATH

    • Test with: gemini -p "Hello world"

  • Claude Code installed and configured

Installation

  1. Clone or download this repository:

    git clone <repository-url>
    cd gemini-mcp-server
  2. Install dependencies:

    npm install
  3. Build the project:

    npm run build

Claude Code Configuration

claude mcp add gemini-cli node /absolute/path/to/gemini-mcp-server/dist/index.js

Method 2: Manual Configuration

Edit your Claude Code configuration file (~/.claude.json):

{
  "mcpServers": {
    "gemini-cli": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gemini-mcp-server/dist/index.js"]
    }
  }
}

Important: Use the absolute path to your built index.js file.

Method 3: Development Mode

For development, you can run directly with ts-node:

{
  "mcpServers": {
    "gemini-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["ts-node", "/absolute/path/to/gemini-mcp-server/src/index.ts"]
    }
  }
}

Setup Verification

  1. Restart Claude Code after configuration changes

  2. Check MCP server status:

    claude mcp list
  3. Verify in Claude Code:

    • Run /mcp command

    • Should show gemini-cli: connected

  4. Test the integration:

    Hey Claude, use the gemini-cli tool to ask: "What is TypeScript?"

Available Tools

gemini_query

Executes a query using the local Gemini CLI tool.

Parameters:

  • prompt (string, required): The text prompt to send to Gemini

  • model (string, optional): Gemini model to use (defaults to gemini-2.5-flash)

Example usage in Claude Code:

Please use the gemini_query tool with prompt: "Explain the difference between async and await"

# With model selection (otherwise defaults to gemini-2.5-flash)
Please use the gemini_query tool with prompt: "What is TypeScript?" and model: "gemini-1.5-flash"

Development

Project Structure

gemini-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── gemini-cli.ts     # CLI wrapper
│   └── types.ts          # TypeScript interfaces
├── dist/                 # Compiled output
├── package.json
├── tsconfig.json
├── PLAN.md              # Implementation details
└── README.md            # This file

Development Commands

# Install dependencies
npm install

# Build for production
npm run build

# Development with auto-reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Development Mode

For active development, you can run the server directly:

npm run dev

Then configure Claude Code to use ts-node as shown in Method 3 above.

Troubleshooting

Common Issues

  1. "Connection closed" error

    • Ensure you're using absolute paths in configuration

    • Check that Node.js can execute the built file

    • Verify the gemini CLI is in your PATH

  2. "Command not found: gemini"

    • Install the Gemini CLI tool

    • Ensure it's in your system PATH

    • Test manually: gemini -p "test"

  3. Server not appearing in /mcp

    • Restart Claude Code after configuration changes

    • Check the configuration file syntax

    • Verify absolute paths are correct

  4. Tool not available

    • Run claude mcp list to check server status

    • Look for connection errors in Claude Code logs

Debugging

  1. Test the server manually:

    node dist/index.js
    # Send JSON-RPC messages via stdin for testing
  2. Test with simulated responses (when Gemini CLI quota is exhausted):

    GEMINI_TEST_MODE=true node dist/index.js
    # Uses simulated responses instead of calling Gemini CLI
  3. Check Gemini CLI directly:

    # Test with default model (gemini-2.5-flash)
    gemini -m gemini-2.5-flash -p "Hello world"
  4. Verify Claude Code configuration:

    claude mcp list

Testing the MCP Server

Test 1: Basic Server Test

cd /Users/zain/code/mcp/gemini-mcp-claude
node dist/index.js

Then send these JSON-RPC messages one by one:

# 1. Initialize the server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}

# 2. List available tools
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

# 3. Test basic query (uses gemini-2.5-flash by default)
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"gemini_query","arguments":{"prompt":"What is 2+2?"}}}

# 4. Test with model override
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"gemini_query","arguments":{"prompt":"Hello world","model":"gemini-1.5-flash"}}}

Press Ctrl+C to exit when done.

Test 2: Test Mode (If Quota Exhausted)

cd /Users/zain/code/mcp/gemini-mcp-claude
GEMINI_TEST_MODE=true node dist/index.js

Send the same JSON-RPC messages as above. You'll get simulated responses instead of hitting the Gemini API.

Test 3: Verify Gemini CLI Directly

# Test default model
gemini -m gemini-2.5-flash -p "What is 2+2?"

# Test alternative model
gemini -m gemini-1.5-flash -p "Hello world"

Test 4: Configure in Claude Code

# Add to Claude Code
claude mcp add gemini-cli node $(pwd)/dist/index.js

# Verify configuration
claude mcp list

# Test in Claude Code
# Run /mcp command to see connection status

Expected Results

  • Initialize: Returns server info with protocol version

  • List tools: Shows gemini_query tool with model parameter support

  • Tool calls: Return Gemini responses or proper error messages

  • Test mode: Returns simulated responses immediately

  • Claude Code: Shows gemini-cli: connected status

If you hit quota limits, the server will timeout after 5 minutes (or 10 seconds in test mode) and return a proper error message.

Testing

The project includes comprehensive test suites:

Running Tests

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

Test Coverage

  • Unit Tests: tests/gemini-cli.test.ts - Tests for CLI wrapper functions

  • Integration Tests: tests/mcp-server.test.ts - Full MCP server testing

  • JSON Error Handling: Tests for robust JSON parsing

  • Model Selection: Tests for default and custom model usage

  • Validation: Tests for input validation and error cases

The test suite provides:

  • 92%+ coverage of the CLI module

  • Full MCP protocol compliance testing

  • Error scenario testing (invalid JSON, timeouts, etc.)

  • Both test and production mode validation

Security Notes

  • The server validates input to prevent command injection

  • Prompts are properly escaped when passed to the shell

  • Command execution is limited by timeout (5 minutes for production, 10 seconds for test mode)

  • Only stderr is used for logging (stdout reserved for MCP protocol)

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Test with Claude Code

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Available Tools

1 tool
gemini_queryA

Execute a query using the local Gemini CLI tool. Best used for: 1) Detailed codebase analysis requiring deep understanding of multiple files and complex relationships, 2) Web searches for current documentation, API references, and coding best practices, 3) Getting a different AI perspective on complex technical problems, 4) Research tasks that benefit from Gemini's training data and capabilities. 5) Code reviews, to get a different perspective on potential issues and improvements.

Inputs: prompt (required), model.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clearly defined as executing queries via the Gemini CLI.

    Naming Consistency4/5

    The single tool name 'gemini_query' follows a clear noun_verb pattern and is descriptive. Since there is only one tool, consistency cannot be fully assessed, but the name is reasonable and follows common conventions.

    Tool Count3/5

    A server with a single tool feels thin for the broad range of tasks described (code analysis, web search, code review). While a single tool can be acceptable for a simple CLI wrapper, the scope of use cases suggests more tools might be expected.

    Completeness3/5

    The single tool appears to cover a wide range of query types, but the lack of any additional tools for managing sessions, configurations, or other CLI capabilities leaves notable gaps. The surface is functional but not fully complete for a comprehensive Gemini CLI integration.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers