🍌 Gemini Image MCP Server

MCP Server for image generation and editing using Google Gemini API (Imagen 4 model). Easily integrate AI image generation into Claude Desktop, Claude Code, Cursor, Windsurf, and other MCP-compatible tools!

✨ Features

• 🎨 Image Generation: Create high-quality images from text prompts
• ✏️ Image Editing: Edit existing images using natural language
• 📐 Custom Aspect Ratios: Support for multiple formats (1:1, 16:9, 9:16, 4:3, 21:9, etc.)
• 🔄 Base64 Output: Returns images in base64 for easy manipulation
• 🚀 Easy Integration: Use via npx without installation
• 🔒 Secure: API key via environment variable
• 📝 TypeScript: Fully typed for better DX

📋 Prerequisites

• Node.js >= 18
• Google Gemini API Key (Get one here)

🚀 Quick Installation

Via NPX (Recommended)

No installation needed! Use directly with npx:

npx gemini-image-mcp <YOUR_API_KEY>

Global Installation

npm install -g gemini-image-mcp
gemini-image-mcp <YOUR_API_KEY>

Local Installation

npm install gemini-image-mcp

🎯 How to Use

1. Claude Desktop Integration

Edit the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "GEMINI_MODEL": "gemini-2.5-flash-image"
      }
    }
  }
}

2. Claude Code Integration

claude mcp add gemini-image \
  -e GEMINI_API_KEY=your-api-key \
  -e GEMINI_MODEL=gemini-2.5-flash-image \
  -- npx -y gemini-image-mcp

Or add to .claude.json in your project:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Cursor IDE Integration

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Windsurf IDE Integration

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

🛠️ Available Tools

1. generate_image

Generates an image from a text prompt.

Parameters:

• prompt (required): Detailed image description
• aspect_ratio (optional): Image format (default: "1:1")
• image_only (optional): Return only image without text (default: false)

Examples:

// Basic square image
generate_image({
  prompt: "A beautiful sunset over mountains with a lake reflection"
})

// Widescreen format
generate_image({
  prompt: "Futuristic city skyline at night with neon lights",
  aspect_ratio: "16:9"
})

// Vertical portrait
generate_image({
  prompt: "Portrait of a wise old wizard with a long beard",
  aspect_ratio: "9:16",
  image_only: true
})

2. edit_image

Edits an existing image using a text prompt.

Parameters:

• prompt (required): Description of desired edits
• image_path (required): Absolute path to the image
• aspect_ratio (optional): Output image format

Examples:

// Add elements
edit_image({
  prompt: "Add a wizard hat on the cat's head",
  image_path: "/path/to/cat.png"
})

// Change style
edit_image({
  prompt: "Transform this photo into a watercolor painting style",
  image_path: "/absolute/path/to/photo.jpg",
  aspect_ratio: "4:3"
})

// Remove elements
edit_image({
  prompt: "Remove the background and replace with a sunset beach scene",
  image_path: "/Users/you/images/portrait.png"
})

3. generate_image_base64

Generates an image and returns it as base64 (without saving file).

Parameters:

• prompt (required): Image description
• aspect_ratio (optional): Image format (default: "1:1")

📐 Supported Aspect Ratios

| Ratio | Resolution | Tokens | Ideal Use | |-------|-----------|--------|-----------| | 1:1 | 1024x1024 | 1290 | Social posts, avatars | | 16:9 | 1344x768 | 1290 | Banners, presentations | | 9:16 | 768x1344 | 1290 | Stories, mobile | | 4:3 | 1184x864 | 1290 | Classic monitors | | 3:4 | 864x1184 | 1290 | Portraits | | 21:9 | 1536x672 | 1290 | Ultrawide, cinema | | 2:3 | 832x1248 | 1290 | Book covers | | 3:2 | 1248x832 | 1290 | Photography | | 4:5 | 896x1152 | 1290 | Instagram portrait | | 5:4 | 1152x896 | 1290 | Legacy monitors |

💡 Usage Examples in Claude

After configuring the MCP, you can use it directly in Claude:

Image Generation

Create an image of a panda eating bamboo in a Japanese zen garden,
watercolor style. Use 16:9 format.

Image Editing

Take the image at /Users/me/Downloads/photo.jpg and add a cowboy
hat to the main character.

Multiple Variations

Generate 3 logo variations for a coffee shop called "Aurora Café",
minimalist style, square format.

🎨 Prompt Tips

For Photorealistic Images

A photorealistic close-up portrait of an elderly Japanese ceramicist
with deep wrinkles and a warm smile. The setting is his rustic workshop.
Soft golden hour lighting. Captured with 85mm portrait lens. Serene mood.

For Illustrations

A kawaii-style sticker of a happy red panda wearing a tiny bamboo hat,
munching on a green bamboo leaf. Bold clean outlines, vibrant colors,
white background.

For Logos

Create a modern minimalist logo for a tech startup called 'NeuralFlow'.
Clean sans-serif font. Simple abstract neural network icon integrated
with text. Black and white color scheme.

🔧 Local Development

Clone and Setup

git clone https://github.com/elhombrejd/gemini-image-mcp.git
cd gemini-image-mcp
npm install

Development

# Development mode (hot reload)
npm run dev

# Build
npm run build

# Test locally
node dist/index.js YOUR_API_KEY

Project Structure

gemini-image-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── api-client.ts     # Gemini API client
│   └── types.ts          # TypeScript definitions
├── dist/                 # Compiled code
├── package.json
├── tsconfig.json
├── README.md
└── .gitignore

🌟 Available Models

• gemini-2.5-flash-image (default) - Fast and efficient

To use a different model, set GEMINI_MODEL:

{
  "env": {
    "GEMINI_API_KEY": "your-key",
    "GEMINI_MODEL": "gemini-4.5-pro-image"
  }
}

⚠️ Limitations

• Best performance with languages: EN, es-MX, ja-JP, zh-CN, hi-IN
• Does not support audio or video inputs
• Maximum of 3 input images for editing

🐛 Troubleshooting

Error: "API key is required"

Make sure GEMINI_API_KEY is set in the environment or passed as an argument.

Error: "Could not read image file"

• Verify the path is absolute
• Confirm the file exists
• Only PNG and JPEG supported

Image not generated

• Check your API quota
• Prompt may violate content policies
• Try a more specific prompt

MCP doesn't appear in Claude

• Completely restart Claude Desktop
• Verify JSON is valid
• Check logs at: ~/Library/Logs/Claude/ (macOS)

📚 Resources

• Gemini API Docs
• MCP Protocol
• Get API Key
• MCP SDK

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

📄 License

MIT License - see LICENSE for details.

👤 Author

Created with ❤️ by @elhombrejd using Google Gemini API

🙏 Acknowledgments

• Google for providing the amazing Gemini API
• Anthropic for the MCP protocol
• Open source community

🌟 If this project was helpful, consider giving it a star!

📮 Issues or suggestions? Open an issue