image-generation-mcp
An MCP (Model Context Protocol) server for generating blog and social media images using AI. Currently supports Google's Gemini/Nano Banana image generation models with a provider architecture designed for easy extension.
Install: npx -y image-generation-mcp
Features
- Platform Presets: Pre-configured dimensions for Ghost, Medium, Instagram, Twitter, LinkedIn, YouTube, and more
- Multiple Quality Levels: Standard (fast) or High (uses Gemini Pro for better quality)
- Auto-Save: Images are always saved to disk (never lost as base64-only responses)
- PNG Metadata: Prompt, model, style, and generation info embedded in every image
- Provider Architecture: Extensible design to support multiple AI providers
- Security First: Input validation, prompt sanitization, safe error handling
Quick Start
Environment Variables
| Variable | Required | Description |
|---|---|---|
GOOGLE_API_KEY | Yes | Your Google AI API key for Gemini |
IMAGE_OUTPUT_DIR | No | Default directory for saved images (defaults to ./generated-images) |
Get your API key from Google AI Studio.
Claude Code Setup
Option 1: Published Package (Recommended)
# Add to Claude Code (user scope - available in all projects)
claude mcp add image-gen --scope user -e GOOGLE_API_KEY=your-api-key -- npx -y image-generation-mcp
# Or add to current project only
claude mcp add image-gen -e GOOGLE_API_KEY=your-api-key -- npx -y image-generation-mcp
Option 2: Local Development
# From the project directory, build first
npm run build
# Add local server to Claude Code
claude mcp add image-gen -e GOOGLE_API_KEY=your-api-key -- node /absolute/path/to/image-generation-mcp/dist/index.js
Option 3: Manual Configuration
Add to ~/.claude.json (user scope) or .mcp.json (project scope):
{
"mcpServers": {
"image-gen": {
"type": "stdio",
"command": "npx",
"args": ["-y", "image-generation-mcp"],
"env": {
"GOOGLE_API_KEY": "your-api-key-here"
}
}
}
}
For local development:
{
"mcpServers": {
"image-gen": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/image-generation-mcp/dist/index.js"],
"env": {
"GOOGLE_API_KEY": "your-api-key-here"
}
}
}
}
Verify Installation
# List configured MCP servers
claude mcp list
# Check status within Claude Code
/mcp
Claude Desktop Setup
Add to your claude_desktop_config.json:
{
"mcpServers": {
"image-gen": {
"command": "npx",
"args": ["-y", "image-generation-mcp"],
"env": {
"GOOGLE_API_KEY": "your-api-key-here"
}
}
}
}
Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Tools
generate_blog_image
Generate an image for blog posts or social media.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Description of the image to generate |
format | string | No | Platform preset (default: ghost-banner) |
quality | string | No | standard or high (default: standard) |
style | string | No | Style hint (e.g., "photorealistic", "illustration") |
title | string | No | Blog post title for context |
outputPath | string | No | Path to save the image (defaults to ./generated-images/ with timestamp) |
provider | string | No | Provider to use (default: gemini) |
Example:
Generate a blog banner for my post about TypeScript best practices.
Use format: medium-ghost-spooky, style: modern minimalist
list_image_formats
List all available image format presets.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Filter by category: blog, social, video, generic |
Available Formats
Blog Platforms
| Format | Dimensions | Ratio | Description |
|---|---|---|---|
ghost-banner | 1200x675 | 16:9 | Featured image for Ghost blog posts |
ghost-feature | 2000x1125 | 16:9 | High-resolution feature image for Ghost |
medium-ghost-spooky | 2560x1440 | 16:9 | Premium high-resolution blog banner (QHD) |
medium-banner | 1400x788 | 16:9 | Banner image for Medium articles |
substack-header | 1456x816 | 16:9 | Header image for Substack posts |
wordpress-featured | 1200x675 | 16:9 | Featured image for WordPress posts |
Social Media
| Format | Dimensions | Ratio | Description |
|---|---|---|---|
instagram-post | 1080x1080 | 1:1 | Square post for Instagram feed |
instagram-story | 1080x1920 | 9:16 | Vertical story/reel for Instagram |
twitter-post | 1200x675 | 16:9 | Image for Twitter/X posts |
linkedin-post | 1200x628 | ~1.91:1 | Image for LinkedIn posts |
facebook-post | 1200x630 | ~1.91:1 | Image for Facebook posts |
Video Platforms
| Format | Dimensions | Ratio | Description |
|---|---|---|---|
youtube-thumbnail | 1280x720 | 16:9 | Thumbnail for YouTube videos |
youtube-banner | 2560x1440 | 16:9 | Channel banner for YouTube |
Generic
| Format | Dimensions | Ratio | Description |
|---|---|---|---|
square | 1024x1024 | 1:1 | Generic square image |
landscape | 1920x1080 | 16:9 | Standard landscape (1080p) |
landscape-4k | 3840x2160 | 16:9 | 4K landscape image |
portrait | 1080x1920 | 9:16 | Standard portrait/vertical image |
PNG Metadata
Every generated PNG image includes embedded metadata:
| Field | Description |
|---|---|
Description | The original prompt |
AI-Model | Model used (e.g., gemini-2.5-flash-image) |
AI-Provider | Provider name (gemini) |
Image-Format | Preset used (e.g., twitter-post) |
AI-Style | Style hint if specified |
Title | Blog post title if specified |
Creation-Time | ISO timestamp |
Software | image-generation-mcp |
View metadata:
# macOS/Linux
strings your-image.png | grep -E "^(Description|AI-|Title|Creation)"
# Or use exiftool
exiftool your-image.png
Security
This MCP server implements several security measures:
- Input Validation: Prompts are validated for length and sanitized
- Prompt Injection Protection: Suspicious patterns are blocked
- Path Traversal Prevention: Output paths are validated
- Safe Error Messages: API keys and sensitive data are never exposed in errors
- No Logging of Secrets: API keys are never logged
⚠️ Disclaimer
This is a simple, vibe-coded MCP server for generating images. It is provided as-is for convenience and educational purposes.
What You Should Know
-
API Key Security: Your
GOOGLE_API_KEYis as safe as you make it. We do not store, log, or transmit your API key anywhere except to Google's API. You are responsible for:- Keeping your API key secure
- Not committing it to version control
- Rotating it if you suspect it has been compromised
-
Data Transmission: Your prompts and generated images are sent to/from Google's Gemini API. Review Google's AI Terms of Service for their data handling policies.
-
No Warranty: This software is provided "AS IS", without warranty of any kind. The authors are not liable for any damages, data loss, API costs, or other issues arising from use of this software.
-
API Costs: Image generation may incur costs on your Google Cloud account. Monitor your usage and set up billing alerts.
-
Content Responsibility: You are responsible for the prompts you submit and the images you generate. Do not use this tool to generate harmful, illegal, or policy-violating content.
License
MIT License - see LICENSE for full terms.
By using this software, you acknowledge that you have read and understood these terms.
Adding New Providers
The server uses a provider interface pattern. To add a new provider:
- Create a new file in
src/providers/implementingImageProvider - Register it in
src/providers/index.ts
// src/providers/my-provider.ts
import { ImageProvider, ImageGenerationOptions, GeneratedImage } from "./types.js";
export class MyProvider implements ImageProvider {
readonly name = "my-provider";
isConfigured(): boolean { /* ... */ }
generateImage(options: ImageGenerationOptions): Promise<GeneratedImage> { /* ... */ }
getSupportedAspectRatios(): string[] { /* ... */ }
getMaxResolution(): { width: number; height: number } { /* ... */ }
}
Development
# Install dependencies
npm install
# Build
npm run build
# Run locally
GOOGLE_API_KEY=your-key node dist/index.js
# Watch mode
npm run dev
# Run tests
npm test
# Lint and format
npm run lint
npm run format
Publishing to npm
# 1. Make sure you're logged in to npm
npm login
# 2. Update version in package.json (if needed)
npm version patch # or minor, major
# 3. Run all checks
npm run check
# 4. Publish
npm publish
# 5. After publishing, users can install with:
# npx image-generation-mcp
# or: npm install -g image-generation-mcp
License
MIT