Gemini - Helper Friend MCP

Your autonomous AI helper that works on your codebase using Gemini CLI

What is This?

Gemini Helper Friend is a Model Context Protocol (MCP) server that gives AI assistants like Claude the ability to delegate complex analysis tasks to Google's Gemini CLI. Think of it as your AI assistant calling in a specialist consultant for deep codebase analysis.

Why Use This?

• 🤖 Autonomous Execution: YOLO mode enabled by default - Gemini works independently
• 📖 Deep Code Analysis: Gemini reads and analyzes your entire codebase
• 🔍 Comprehensive Research: Uses 100+ tool calls for thorough investigation
• 📝 Structured Documentation: Creates organized reports in helper-friend-docs/
• ⚡ Auto-Model Selection: Gemini CLI picks the best model (gemini-3-pro or gemini-3-flash)

Prerequisites

1. Node.js 16.0.0 or higher
2. Gemini CLI installed and authenticated:

   npm install -g @google/generative-ai-cli
   gemini auth login

Installation

npm install -g gemini-helper-friend-mcp

Configuration

Add to your MCP client config (e.g., Claude Desktop):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

Or use npx (no installation required):

{
  "mcpServers": {
    "gemini-helper-friend": {
      "command": "npx",
      "args": ["-y", "gemini-helper-friend-mcp@latest"]
    }
  }
}

Usage

The MCP exposes a single powerful tool: gemini-task

Basic Usage

Ask Claude: "Use gemini-task to analyze the authentication flow in @src/auth/"

Structured Task Format (Recommended)

🎯 OBJECTIVE: Perform comprehensive security audit of API endpoints

📁 SCOPE: Analyze @src/routes/ @src/controllers/ @src/middleware/auth.ts

❓ QUESTIONS:
1. Are all endpoints properly authenticated?
2. Is input validation sufficient?
3. Are there SQL injection or XSS vulnerabilities?
4. How is rate limiting implemented?
5. Are sensitive data properly encrypted?

📤 OUTPUT: Create detailed security report in helper-friend-docs/security-audit/

Common Use Cases

Code Analysis:

"Analyze the data flow from API request to database in @src/"
"Map all dependencies and their versions in this project"

Architecture Review:

"Document the overall architecture of this codebase"
"Identify patterns and anti-patterns in @src/services/"

Security Audit:

"Find potential security vulnerabilities in @src/auth/"
"Review all API endpoints for proper authentication"

Documentation:

"Generate API documentation from @src/routes/"
"Create onboarding guide for new developers"

How It Works

You (via Claude) → gemini-task → Gemini CLI (YOLO mode) → Analysis Results
                                      ↓
                              Reads your codebase
                              Uses MCP tools
                              Creates documentation

Default Execution:

gemini --yolo -p "[your task + MANDATORY PROTOCOL suffix]"

Features

YOLO Mode (Default)

Gemini automatically approves all actions for autonomous execution. Safe for read-only analysis tasks.

Mandatory Protocol Suffix

Every task includes instructions for Gemini to:

• Act as VP-level software architect
• Use 100+ tool calls for thoroughness
• Create structured docs in helper-friend-docs/
• Never edit code, only analyze and document
• Cite all sources and ground in evidence

LLM-Friendly Error Handling

Errors are formatted with:

• Error Code: QUOTA_EXCEEDED, CLI_NOT_FOUND, TIMEOUT, etc.
• Message: Detailed error description
• Suggestion: Actionable fix
• Retryable: Whether you can retry

Tool Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | task | string | ✅ Yes | - | Your task for Gemini (min 10 chars) | | model | string | No | auto | Override model: gemini-3-pro or gemini-3-flash | | sandbox | boolean | No | false | Run in sandbox mode | | include_suffix | boolean | No | true | Append MANDATORY PROTOCOL |

Configuration (YAML)

Tool configuration is defined in src/config/yaml/tools.yaml:

settings:
  defaults:
    model: ""  # Auto-select
    yolo_mode: true
    append_suffix: true

prompt_suffix:
  enabled: true
  content: |
    [MANDATORY PROTOCOL instructions...]

Development

# Clone and install
git clone https://github.com/jamubc/gemini-mcp-tool.git
cd gemini-mcp-tool
npm install

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

Troubleshooting

"Gemini CLI not found"

npm install -g @google/generative-ai-cli
which gemini  # Should show path

"API quota exceeded"

• Wait for quota reset (daily limit)
• Gemini CLI has generous free tier limits

"Request timed out"

• Try simpler task or reduce file scope
• Set include_suffix: false for quick queries

License

MIT © jamubc

Contributing

Issues and PRs welcome at github.com/jamubc/gemini-mcp-tool