Gemini MCP Server

An MCP Server that provides access to the Gemini Suite.

✨ Features

• Support for 1.5 through 2.5 pro
• Nano Banana
• Embeddings
• File Upload
• Batch (NLP and Embeddings)

🚀 Quick Start

Option 1: NPX (No Install Required)

claude mcp add gemini -s user --env GEMINI_API_KEY=YOUR_KEY_HERE -- npx -y @mintmcqueen/gemini-mcp@latest

Option 2: Global Install

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

# Add to Claude Code
claude mcp add gemini -s user --env GEMINI_API_KEY=YOUR_KEY_HERE -- gemini-mcp

Option 3: Local Project Install

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

# Add to Claude Code (adjust path as needed)
claude mcp add gemini -s 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.

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

generate_images

Generate images from text prompts or edit existing images using Gemini 2.5 Flash Image model.

Parameters:

• prompt (required): Text description of image to generate or editing instructions
• aspectRatio (optional): Image aspect ratio - 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 1:1)
• numImages (optional): Number of images to generate, 1-4 (default: 1). Note: Makes sequential API calls, ~10-15s per image.
• inputImageUri (optional): File URI from uploaded file for image editing (omit for text-to-image generation)
• outputDir (optional): Directory to save generated images (default: ./generated-images)
• temperature (optional): Controls randomness (0.0-2.0, default: 1.0)

Returns:

• Array of generated images with file paths and base64 data
• Token usage (~1,290-1,300 tokens per image)
• All images include SynthID watermark

Performance Note: The Gemini API generates one image per request. When numImages > 1, the tool makes multiple sequential API calls to generate the requested number of images. Expect ~10-15 seconds per image.

Text-to-Image Example:

generate_images({
  prompt: "A photorealistic coffee cup on a wooden table",
  aspectRatio: "16:9",
  numImages: 2
})
// Generates 2 images saved to ./generated-images/

Image Editing Example:

// First, upload the image to edit
upload_file({ filePath: "./photo.jpg" })
// Returns: { uri: "files/abc123" }

// Then edit it
generate_images({
  prompt: "Add a wizard hat to the subject",
  inputImageUri: "files/abc123"
})
// Generates edited image saved to ./generated-images/

🆕 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

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