Gemini MCP server for AI agents

The Gemini MCP Server allows Claude Desktop to generate images through Google's Gemini AI models. It acts as a connector that enables Claude to harness Gemini's image generation capabilities through the Model Context Protocol (MCP).

Requirements

Node.js 16.x or higher
Claude Desktop application
Google Gemini API key (obtain from Google AI Developer site)

Installation Options

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

Docker Installation

# Clone the repository
git clone https://github.com/Garblesnarff/gemini-mcp-server.git
cd gemini-mcp-server

# Build the Docker image
docker build -t gemini-mcp-server .

# Run the container
docker run -e GEMINI_API_KEY=your_api_key -e OUTPUT_DIR=/app/output -v $(pwd)/output:/app/output gemini-mcp-server

Setup Process

The setup wizard guides you through configuration:

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

Using the Gemini MCP Server

After installation and configuration:

Restart Claude Desktop to enable the Gemini MCP server
Start a conversation with Claude
Ask Claude to generate an image with prompts like:
- "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 and provide you with the path to the saved image.

Advanced Options

Customize image generation with additional parameters:

Style: Specify styles like "realistic", "artistic", "minimalistic"
Temperature: Control creativity/randomness (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:

1. Create Configuration File

{
  "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

#!/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:

{
  "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"
      }
    }
  }
}

Command Line Options

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

Docker Usage

docker run -e GEMINI_API_KEY=your_api_key -e OUTPUT_DIR=/app/output -v $(pwd)/output:/app/output gemini-mcp-server

Environment Variables for Docker

GEMINI_API_KEY: Your Google Gemini API key (required)
OUTPUT_DIR: Directory inside the container to save generated images (default: /app/output)
DEBUG: Enable debug logging (default: false)
LOG_LEVEL: Set log level (default: INFO)

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

Enabling Debug Mode

npx gemini-mcp-server --debug

Or set the environment variable:

export DEBUG=true
npx gemini-mcp-server

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.