Gemini MCP Server

An MCP Server that provides access to Google's Gemini models with file uploads and Batch API integration.

✨ Features

• Multiple Gemini Models on Request: Gemini 2.5 Pro, 2.5 Flash, 2.0 Flash, and Embedding-001
• 🆕 Batch API Integration (v0.3.0): Async processing at 50% cost with ~24hr turnaround
  • 11 batch tools for content generation and embeddings
  • Intelligent JSONL conversion (CSV, JSON, TXT, MD)
  • Complete workflow automation
  • 8 embedding task types with AI recommendations
• Advanced File Handling: Upload and process 40+ files with batch support
• Automatic Configuration: Interactive API key setup for Claude Code & Claude Desktop
• Conversation Management: Multi-turn conversations with history tracking
• Type Safety: Full TypeScript implementation with proper type definitions
• Production Ready: Retry logic, error handling, and file state monitoring

🚀 Quick Start

Option 1: Global Install (Recommended for Claude Code)

# Install globally
npm install -g @mintmcqueen/gemini-mcp

# Add to Claude Code
claude mcp add --transport stdio gemini --scope user --env GEMINI_API_KEY=YOUR_KEY_HERE -- gemini-mcp

Option 2: Local Project Install

# Install in your project
npm install @mintmcqueen/gemini-mcp

# Add to Claude Code (adjust path as needed)
claude mcp add --transport stdio gemini --scope project --env GEMINI_API_KEY=YOUR_KEY_HERE -- node node_modules/@mintmcqueen/gemini-mcp/build/index.js

After any installation method, restart Claude Code and you're ready to use Gemini.

🔑 API Key Setup

Get Your API Key

1. Visit Google AI Studio
2. Create a new API key (free)
3. Copy your key (starts with "AIza...")

Configure Anytime

npm run configure

The configuration wizard will:

• Validate your API key format
• Test the key with a real Gemini API request
• Write configuration to your chosen location(s)
• Provide next steps

📦 What Gets Configured

Claude Code (Global Install)

• File: ~/.claude.json (user scope)
• Format: stdio MCP server with environment variables

{
  "mcpServers": {
    "gemini": {
      "type": "stdio",
      "command": "gemini-mcp",
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Code (Local Install)

• File: .mcp.json (project scope)
• Format: stdio MCP server with node execution

{
  "mcpServers": {
    "gemini": {
      "type": "stdio",
      "command": "node",
      "args": ["node_modules/@mintmcqueen/gemini-mcp/build/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop

• File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Format: Standard MCP server configuration

Shell Environment

• File: ~/.zshrc or ~/.bashrc
• Format: export GEMINI_API_KEY="your-key-here"

Usage

MCP Tools

The server provides the following tools:

chat

Send a message to Gemini with optional file attachments.

Parameters:

• message (required): The message to send
• model (optional): Model to use (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
• files (optional): Array of files with base64 encoded data
• temperature (optional): Controls randomness (0.0-2.0)
• maxTokens (optional): Maximum response tokens
• conversationId (optional): Continue an existing conversation

start_conversation

Start a new conversation session.

Parameters:

• id (optional): Custom conversation ID

clear_conversation

Clear a conversation session.

Parameters:

• id (required): Conversation ID to clear

🆕 Batch API Tools (v0.3.0)

Process large-scale tasks asynchronously at 50% cost with ~24 hour turnaround.

Content Generation

Simple (Automated):

// One-call solution: Ingest → Upload → Create → Poll → Download
batch_process({
  inputFile: "prompts.csv",  // CSV, JSON, TXT, or MD
  model: "gemini-2.5-flash"
})
// Returns: Complete results with metadata

Advanced (Manual Control):

// 1. Convert your file to JSONL
batch_ingest_content({ inputFile: "prompts.csv" })
// Returns: { outputFile: "prompts.jsonl", requestCount: 100 }

// 2. Upload JSONL
upload_file({ filePath: "prompts.jsonl" })
// Returns: { uri: "files/abc123" }

// 3. Create batch job
batch_create({
  inputFileUri: "files/abc123",
  model: "gemini-2.5-flash"
})
// Returns: { batchName: "batches/xyz789" }

// 4. Monitor progress
batch_get_status({
  batchName: "batches/xyz789",
  autoPoll: true  // Wait until complete
})
// Returns: { state: "SUCCEEDED", stats: {...} }

// 5. Download results
batch_download_results({ batchName: "batches/xyz789" })
// Returns: { results: [...], outputFile: "results.json" }

Embeddings

Simple (Automated):

// One-call solution with automatic task type prompting
batch_process_embeddings({
  inputFile: "documents.txt",
  // taskType optional - will prompt if not provided
})
// Returns: 1536-dimensional embeddings array

Advanced (Manual Control):

// 1. Select task type (if unsure)
batch_query_task_type({
  context: "Building a search engine"
})
// Returns: { selectedTaskType: "RETRIEVAL_DOCUMENT", recommendation: {...} }

// 2. Ingest content for embeddings
batch_ingest_embeddings({ inputFile: "documents.txt" })
// Returns: { outputFile: "documents.embeddings.jsonl" }

// 3-5. Same as content generation workflow
// 6. Results contain 1536-dimensional vectors

Task Types (8 options):

• SEMANTIC_SIMILARITY - Compare text similarity
• CLASSIFICATION - Categorize content
• CLUSTERING - Group similar items
• RETRIEVAL_DOCUMENT - Build search indexes
• RETRIEVAL_QUERY - Search queries
• CODE_RETRIEVAL_QUERY - Code search
• QUESTION_ANSWERING - Q&A systems
• FACT_VERIFICATION - Fact-checking

Job Management

// Cancel running job
batch_cancel({ batchName: "batches/xyz789" })

// Delete completed job
batch_delete({ batchName: "batches/xyz789" })

Supported Input Formats:

• CSV (converts rows to requests)
• JSON (wraps objects as requests)
• TXT (splits lines as requests)
• MD (markdown sections as requests)
• JSONL (ready to use)

MCP Resources

gemini://models/available

Information about available Gemini models and their capabilities.

gemini://conversations/active

List of active conversation sessions with metadata.

🔧 Development

npm run build        # Build TypeScript
npm run watch        # Watch mode
npm run dev          # Build + auto-restart
npm run inspector    # Debug with MCP Inspector
npm run configure    # Reconfigure API key

Connection Failures

If Claude Code fails to connect:

1. Verify your API key is correct
2. Check that the command path is correct (for local installs)
3. Restart Claude Code after configuration changes

🔒 Security

• API keys are never logged or echoed
• Files created with 600 permissions (user read/write only)
• Masked input during key entry
• Real API validation before storage

🤝 Contributing

Contributions are welcome! This package is designed to be production-ready with:

• Full TypeScript types
• Comprehensive error handling
• Automatic retry logic
• Real API validation

📄 License

MIT - see LICENSE file

🙋 Support

• MCP Protocol: https://modelcontextprotocol.io
• Gemini API Docs: https://ai.google.dev/docs