Skip to main content
Glama

Gemini MCP Server

by mintmcqueen
npmGitHub
JavaScript
MIT License
23
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

Enables interaction with Google's Gemini AI models including file uploads, conversation management, and batch API processing for large-scale tasks at reduced costs. Supports multiple Gemini models with advanced features like embeddings generation and automated workflow processing.

  1. โœจ Features
    1. ๐Ÿš€ Quick Start
      1. Option 1: Global Install (Recommended for Claude Code)
      2. Option 2: Local Project Install
    2. ๐Ÿ”‘ API Key Setup
      1. Get Your API Key
      2. Configure Anytime
    3. ๐Ÿ“ฆ What Gets Configured
      1. Claude Code (Global Install)
      2. Claude Code (Local Install)
      3. Claude Desktop
      4. Shell Environment
    4. Usage
      1. MCP Tools
      2. ๐Ÿ†• Batch API Tools (v0.3.0)
      3. MCP Resources
    5. ๐Ÿ”ง Development
      1. Connection Failures
    6. ๐Ÿ”’ Security
      1. ๐Ÿค Contributing
        1. ๐Ÿ“„ License
          1. ๐Ÿ™‹ Support

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/mintmcqueen/gemini-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server