Gemini MCP Server for Claude Desktop

A Model Context Protocol (MCP) server that enables Claude Desktop to generate images using Google's Gemini AI models.

🌟 Features

Generate images directly from Claude Desktop using Google's Gemini models
Easy setup wizard for configuration
Customizable image generation parameters
Integration with Claude Desktop's MCP server system
Detailed logging and debugging capabilities

📋 Requirements

Node.js 16.x or higher
Claude Desktop application
Google Gemini API key (Get one here)

🚀 Installation

Global Installation (Recommended)

npm install -g gemini-mcp-server

# Run the setup wizard
npx gemini-mcp-setup

Local Installation

# Create a directory for the server
mkdir gemini-mcp-server
cd gemini-mcp-server

# Install locally
npm install gemini-mcp-server

# Run the setup wizard
npx gemini-mcp-setup

⚙️ Setup

The setup wizard will guide you through the configuration process:

Enter your Google Gemini API key
Specify the directory for saving generated images
Configure logging and model settings
Automatically create a wrapper script for Claude Desktop
Update your Claude Desktop configuration

If you prefer manual setup, see the Manual Configuration section below.

🎨 Using the Gemini MCP Server

Once installed and configured, restart Claude Desktop to enable the Gemini MCP server. Then:

Start a conversation with Claude
Ask Claude to generate an image for you, for example:
- "Generate an image of a mountain landscape at sunset"
- "Create a picture of a futuristic city with flying cars"
- "Make an illustration of a cat playing piano"

Claude will call the Gemini API to generate the image and provide you with the path to the saved image file.

Advanced Options

You can customize the image generation with additional parameters:

Style: Specify a style like "realistic", "artistic", "minimalistic", etc.
Temperature: Control the creativity/randomness of the generation (0.0-1.0)

Example: "Generate an image of a cyberpunk city with neon lights in a realistic style with temperature 0.7"

🔧 Manual Configuration

If you prefer not to use the setup wizard, follow these steps:

1. Create Configuration File

Create a JSON configuration file with your settings:

{
  "apiKey": "YOUR_GEMINI_API_KEY_HERE",
  "outputDir": "/path/to/your/output/directory",
  "debug": true,
  "modelOptions": {
    "model": "gemini-2.0-flash-exp",
    "temperature": 0.4
  }
}

2. Create Wrapper Script

Create a bash script to run the server:

#!/bin/bash
# Set environment variables
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"
export OUTPUT_DIR="/path/to/your/output/directory"
export DEBUG="true"

# Execute the server
exec "$(which node)" "$(npm root -g)/gemini-mcp-server/bin/gemini-mcp-server.js"

Make the script executable:

chmod +x gemini-mcp-wrapper.sh

3. Update Claude Desktop Configuration

Edit your ~/.config/claude/claude_desktop_config.json file to add the Gemini MCP server:

{
  "mcpServers": {
    "gemini-image": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/path/to/your/gemini-mcp-wrapper.sh"
      ],
      "env": {
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE",
        "DEBUG": "true"
      }
    }
  }
}

📚 API Documentation

Command Line Interface

gemini-mcp-server [options]

Options:

-k, --api-key <key>: Google Gemini API key
-o, --output-dir <dir>: Directory to save generated images
-d, --debug: Enable debug logging
-c, --config <path>: Path to custom configuration file
-r, --reset-config: Reset configuration to defaults
-v, --version: Display version information

Environment Variables

GEMINI_API_KEY: Your Google Gemini API key
OUTPUT_DIR: Directory to save generated images
DEBUG: Enable debug logging (true or false)
LOG_LEVEL: Set log level (ERROR, WARN, INFO, or DEBUG)
GEMINI_LOG_FILE: Custom log file path

Configuration Options

Option	Description	Default
`apiKey`	Google Gemini API key	(required)
`outputDir`	Directory to save generated images	`~/Claude/gemini-images`
`debug`	Enable debug logging	`false`
`modelOptions.model`	Gemini model to use	`gemini-2.0-flash-exp`
`modelOptions.temperature`	Control creativity/randomness	`0.4`
`modelOptions.topK`	Top-k sampling parameter	`32`
`modelOptions.topP`	Top-p sampling parameter	`1`
`modelOptions.maxOutputTokens`	Maximum output tokens	`8192`

🔍 Troubleshooting

Common Issues

Server doesn't start or Claude can't connect to it

Check the log file at ~/Claude/logs/gemini-image-mcp.log
Verify your API key is correct
Ensure all directories exist and have proper permissions
Restart Claude Desktop

Images aren't being generated

Verify your Google Gemini API key has the correct permissions
Check if the output directory exists and is writable
Examine the logs for specific error messages
Try a different prompt or model

Error: "Method not found"

This usually means Claude is trying to call a method that the MCP server doesn't support. Check the logs to see what method was requested.

Debug Mode

Enable debug mode for more detailed logs:

npx gemini-mcp-server --debug

Or set the environment variable:

export DEBUG=true
npx gemini-mcp-server

📝 License

MIT

🙏 Acknowledgements

Model Context Protocol for the MCP specification
Google Generative AI for the Gemini API
All contributors to this project

Integrations