An MCP Server that provides access to the Gemini Suite.
- Support for 1.5 through 2.5 pro
- Nano Banana
- Embeddings
- File Upload
- Batch (NLP and Embeddings)
claude mcp add gemini -s user --env GEMINI_API_KEY=YOUR_KEY_HERE -- npx -y @mintmcqueen/gemini-mcp@latest# 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# 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.jsAfter any installation method, restart Claude Code and you're ready to use Gemini.
- File:
~/.zshrcor~/.bashrc - Format:
export GEMINI_API_KEY="your-key-here"
The server provides the following tools:
Send a message to Gemini with optional file attachments.
Parameters:
message(required): The message to sendmodel(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 datatemperature(optional): Controls randomness (0.0-2.0)maxTokens(optional): Maximum response tokensconversationId(optional): Continue an existing conversation
Start a new conversation session.
Parameters:
id(optional): Custom conversation ID
Clear a conversation session.
Parameters:
id(required): Conversation ID to clear
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 instructionsaspectRatio(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/Process large-scale tasks asynchronously at 50% cost with ~24 hour turnaround.
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 metadataAdvanced (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" }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 arrayAdvanced (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 vectorsTask Types (8 options):
SEMANTIC_SIMILARITY- Compare text similarityCLASSIFICATION- Categorize contentCLUSTERING- Group similar itemsRETRIEVAL_DOCUMENT- Build search indexesRETRIEVAL_QUERY- Search queriesCODE_RETRIEVAL_QUERY- Code searchQUESTION_ANSWERING- Q&A systemsFACT_VERIFICATION- Fact-checking
// 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)
Information about available Gemini models and their capabilities.
List of active conversation sessions with metadata.
npm run build # Build TypeScript
npm run watch # Watch mode
npm run dev # Build + auto-restart
npm run inspector # Debug with MCP InspectorIf Claude Code fails to connect:
- Verify your API key is correct
- Check that the command path is correct (for local installs)
- Restart Claude Code after configuration changes
- 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
Contributions are welcome! This package is designed to be production-ready with:
- Full TypeScript types
- Comprehensive error handling
- Automatic retry logic
- Real API validation
MIT - see LICENSE file
- MCP Protocol: https://modelcontextprotocol.io
- Gemini API Docs: https://ai.google.dev/docs