Gemini CLI Orchestrator MCP

A lightweight CLI tool and MCP server enabling AI agents to perform deep codebase analysis with Gemini's massive context window.

🚀 Getting Started

Step 1: Install Gemini CLI

npm install -g @google/gemini-cli

Step 2: Install this tool

npm install

Step 3: Test it works

npm run analyze "What does this code do?"

That's it! Authentication happens automatically on first use.

Two Ways to Use

🚀 MCP Server (Recommended for Agents)

Makes this tool available to any AI agent via Model Context Protocol

# Install dependencies
npm install

MCP Configuration by IDE

Claude Code CLI

# Quick setup
claude mcp add gemini-cli-orchestrator node /path/to/your/gemini-cli-orchestrator/mcp-server.mjs

# Or edit ~/.claude/settings.local.json:
{
  "permissions": {
    "allow": ["mcp__gemini-cli-orchestrator__analyze_with_gemini"]
  },
  "mcpServers": {
    "gemini-cli-orchestrator": {
      "command": "node",
      "args": ["/path/to/your/gemini-cli-orchestrator/mcp-server.mjs"]
    }
  }
}

Claude Desktop

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-cli-orchestrator": {
      "command": "node",
      "args": ["/path/to/your/gemini-cli-orchestrator/mcp-server.mjs"]
    }
  }
}

Cursor IDE

Config file: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "gemini-cli-orchestrator": {
      "command": "node",
      "args": ["/path/to/your/gemini-cli-orchestrator/mcp-server.mjs"]
    }
  }
}

Windsurf IDE

Config file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gemini-cli-orchestrator": {
      "command": "node",
      "args": ["/path/to/your/gemini-cli-orchestrator/mcp-server.mjs"],
      "disabled": false
    }
  }
}

📁 Quick Setup: Copy example configs from .ide-configs/ directory

Any agent can now use:

analyze_with_gemini("find security issues", "@src/auth/ @middleware/")
Intelligent file selection guided by tool description
Cross-file analysis with Gemini's massive context window

💻 Direct CLI (For Scripts/Power Users)

Ultra-simple direct usage

Quick Start

# Install
npm install

# Basic usage
npm run analyze "What does this code do?" @src/main.js

# Templates
npm run analyze --template security @src/ @package.json

# Verification (Reddit-style)  
npm run analyze "Is JWT auth implemented?" @src/auth/

# Semantic keywords (NEW!)
npm run analyze "Review authentication security" @authentication

Features

✅ @ syntax file inclusion - @src/ @**/*.js @package.json
✅ Semantic keywords - @authentication @database @config (via .gemini-direct.json)
✅ 5 core templates - security, architecture, performance, quality, debug
✅ Direct Gemini calls - no MCP overhead
✅ Zero configuration - works immediately
✅ Single dependency - just glob

Examples

# File analysis
npm run analyze "Explain this code" @src/main.js

# Directory analysis  
npm run analyze "Review architecture" @src/

# Multiple files
npm run analyze "Compare these" @src/old.js @src/new.js

# Security audit
npm run analyze --template security @src/ @package.json

# Verification questions
npm run analyze "Is error handling robust?" @src/ @api/
npm run analyze "Are WebSocket hooks present?" @src/hooks/
npm run analyze "Is dark mode implemented?" @src/ @styles/

How It Works

The tool has two components:

CLI Tool (gemini-direct.mjs): Aggregates files using @ syntax and sends to Gemini CLI
MCP Server (mcp-server.mjs): Makes the CLI tool available to AI agents via standard protocol

File patterns like @src/ expand to include multiple files in a single Gemini analysis request.

Requirements

Node.js 18+
Google Gemini CLI installed and authenticated (see setup below)

⚡ Quick Setup Check

# 1. Check if Gemini CLI is installed
gemini --version

# 2. Test authentication (will prompt if needed)
echo "Hello" | gemini

# 3. Install this tool
npm install

# 4. Test the tool
npm run analyze "What does this code do?"

Setup

1. Install Gemini CLI

# Install the official Google Gemini CLI
npm install -g @google/gemini-cli

2. Authenticate with Google (OAuth - FREE)

The Gemini CLI uses OAuth authentication. No explicit auth command needed - authentication happens automatically on first use.

# Test authentication (will prompt for login if needed)
echo "Hello Gemini" | gemini

First Run: If not authenticated, Gemini CLI will automatically open your browser for OAuth login.

What Gets Created:

~/.gemini/
├── settings.json          # {"selectedAuthType": "oauth-personal"}
├── oauth_creds.json       # OAuth tokens (auto-refreshed)
├── user_id               # Your unique identifier
└── google_account_id     # Google account reference

How It Works:

First time: Any gemini command opens browser for OAuth
Subsequent calls: Gemini CLI automatically uses stored tokens
Token refresh: Happens automatically when needed
Your tool: Inherits authentication from Gemini CLI

Cross-Platform Paths:

OS	Auth Directory
Linux/macOS	`~/.gemini/`
Windows	`%USERPROFILE%\.gemini\`
Docker	Mount host `~/.gemini/` as volume

Uses Google OAuth authentication (personal Google account).

3. Verify Authentication

# Test that authentication works
echo "Hello Gemini" | gemini
# You should see a response from Gemini

4. Install and Test This Tool

# Clone or download this project
git clone <repository-url>
cd gemini-cli-orchestrator

# Install dependencies
npm install

# Test the tool
npm run analyze "What is 2+2?"

Authentication Details

No Code Changes Needed - Your tool automatically inherits authentication because:

// Spawns gemini CLI with full environment
const child = spawn(geminiPath, ['-m', 'gemini-2.5-flash'], {
  stdio: ['pipe', 'pipe', 'pipe'],
  env: { ...process.env }  // ← Passes through all environment
});

The Gemini CLI handles reading ~/.gemini/oauth_creds.json automatically.

Authentication is handled by the Gemini CLI, so the tool inherits existing credentials automatically.

Troubleshooting

"Command not found: gemini"

# Check if Gemini CLI is installed
npm list -g @google/gemini-cli

# If not installed, install it
npm install -g @google/gemini-cli

"Authentication failed"

# Test authentication (will re-prompt if needed)
echo "test" | gemini

# If still failing, check if ~/.gemini/ directory exists
ls -la ~/.gemini/

"GEMINI_CLI_PATH not found"

The tool automatically finds the Gemini CLI. If you have issues:

# Find where Gemini is installed
which gemini

# Set environment variable if needed (optional)
export GEMINI_CLI_PATH=$(which gemini)

Templates

security - OWASP-style security audit
architecture - System design and patterns analysis
performance - Bottleneck identification and optimization
quality - Code quality and best practices review
debug - Bug identification and troubleshooting

Semantic Keywords

Create a .gemini-direct.json file in your project root to define semantic keywords that map to file patterns:

{
  "aliases": {
    "authentication": ["src/auth/**/*", "middleware/auth*", "**/*auth*"],
    "database": ["src/models/**/*", "src/db/**/*", "**/*model*"],
    "api": ["src/api/**/*", "src/routes/**/*", "**/*controller*"],
    "config": ["*.config.*", ".env*", "package.json"],
    "tests": ["test/**/*", "**/*.test.*", "**/*.spec.*"]
  },
  "limits": {
    "maxFiles": 30,
    "maxCharsPerFile": 8000
  }
}

Usage:

# Instead of guessing project structure
npm run analyze "security audit" @authentication @config

# Works across any project type (JavaScript, Python, Go, etc.)
npm run analyze "find database issues" @database

Distribution

This tool is designed to be:

Copied - 3 files, copy anywhere
Shared - Send to colleagues, zero setup
Embedded - Drop into any project
Global - npm install -g for system-wide use

Perfect for getting real value from Gemini's massive context window without the complexity overhead.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A lightweight MCP server that enables AI agents to perform deep codebase analysis by leveraging Gemini's massive context window for cross-file analysis and intelligent file selection.

Related MCP Servers

Gemini Thinking Server
bartekke8it56w2
A
security
F
license
A
quality
An MCP server implementation that leverages Google's Gemini API to provide analytical problem-solving capabilities through sequential thinking steps without code generation.
Last updated -
1
14
JavaScript
Gemini Context MCP Server
ogoldberg
-
security
F
license
-
quality
An MCP server implementation that maximizes Gemini's 2M token context window with tools for efficient context management and caching across multiple AI client applications.
Last updated -
14
TypeScript
MCP Gemini Server
bsmi021
A
security
A
license
A
quality
A dedicated server that wraps Google's Gemini AI models in a Model Context Protocol (MCP) interface, allowing other LLMs and MCP-compatible systems to access Gemini's capabilities like content generation, function calling, chat, and file handling through standardized tools.
Last updated -
16
20
TypeScript
MIT License
Python Codebase Analysis RAG System
shervinemp
-
security
F
license
-
quality
An MCP server that analyzes Python codebases using AST, stores code elements in a vector database, and enables natural language queries about code structure and functionality using RAG with Google's Gemini models.
Last updated -
1
Python

View all related MCP servers

Gemini CLI Orchestrator MCP