---
slug: "claude-image-gen"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/guinacio/claude-image-gen@master/README.md"
repo: "https://github.com/guinacio/claude-image-gen"
source_file: "README.md"
branch: "master"
---
# Gemini Image Generation - Claude Skill + MCP

AI-powered image generation using Google Gemini, integrated with Claude Code.

## Features

- Generate images from text prompts using Gemini AI
- Proactive Claude skill suggests images for websites, presentations, and more
- **Two execution modes**: CLI script (skill-only) or MCP server (protocol-based)
- Configurable aspect ratios (1:1, 16:9, 9:16, etc.)
- Multiple model support (quality vs speed)
- Images saved to disk with file paths returned

## Prerequisites

- Google Gemini API key ([Get one here](https://aistudio.google.com/apikey))
- Node.js 18+ (only for manual installation)

## Installation

### Quick Install (Claude Code Plugin)

The plugin installs **skill + CLI + MCP server** in one step—no separate configuration needed.

```bash
# Add the marketplace
/plugin marketplace add guinacio/claude-image-gen

# Install the plugin
/plugin install media-pipeline@media-pipeline-marketplace
```

Or install directly from GitHub:

```bash
/plugin install guinacio/claude-image-gen
```

Once installed:
- **Skill** uses the bundled CLI script (no MCP overhead)
- **MCP server** is also available for direct tool calls

> **Tip:** Since the skill runs the CLI directly, you can disable the MCP server in Claude Code's MCP list to reduce startup overhead. The skill will continue to work without it.

---

### Quick Install (Claude Desktop Extension)

For Claude Desktop users, install the pre-built extension:

1. Download `media-pipeline.mcpb` from [Releases](https://github.com/guinacio/claude-image-gen/releases)
2. Open Claude Desktop
3. Go to **Settings** → **Extensions** → **Advanced settings**
4. Click **Install Extension** and select the `.mcpb` file
5. Enter your Gemini API key when prompted

---

### Manual Installation

For developers who want to customize or build from source:

#### 1. Build the MCP Server

```bash
cd mcp-server
npm install
npm run bundle
```

#### 2. Use the Standalone CLI

```bash
cd mcp-server
GEMINI_API_KEY=your-api-key-here node build/cli.bundle.js \
  --prompt "Landing page hero image for a fintech startup" \
  --aspect-ratio "16:9"
```

The CLI runs directly against Gemini and returns structured JSON on stdout. It does not require the MCP server layer.

#### 3. Add to Claude Code

**Option A: Using MCP server**

```bash
claude mcp add --transport stdio media-pipeline \
  --env GEMINI_API_KEY=your-api-key-here \
  -- node /path/to/claude-image-gen/mcp-server/build/bundle.js
```

The `--` separates Claude CLI flags from the server command.

**Option B: Manual config**

Add to your Claude Code config (`~/.claude.json`):

```json
{
  "mcpServers": {
    "media-pipeline": {
      "command": "node",
      "args": ["/path/to/claude-image-gen/mcp-server/build/bundle.js"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "GEMINI_DEFAULT_MODEL": "${GEMINI_DEFAULT_MODEL:-gemini-3-pro-image-preview}",
        "IMAGE_OUTPUT_DIR": "${IMAGE_OUTPUT_DIR:-./generated-images}",
        "GEMINI_REQUEST_TIMEOUT_MS": "${GEMINI_REQUEST_TIMEOUT_MS:-60000}",
        "MEDIA_PIPELINE_LOG_LEVEL": "${MEDIA_PIPELINE_LOG_LEVEL:-info}"
      }
    }
  }
}
```

The `${VAR:-default}` syntax uses environment variables with fallback defaults.

#### 4. Install Skill Manually (Optional)

If not using the plugin:

```bash
cp -r skills/image-generation ~/.claude/skills/
```

#### 4. Build Extension from Source (Optional)

To create your own `.mcpb` extension for Claude Desktop:

```bash
cd mcp-server
npm install -g @anthropic-ai/mcpb
npm run pack:mcpb
```

This creates `mcp-server/media-pipeline.mcpb` using bundled runtime entry points for both the MCP server and the standalone CLI.

## Usage

### Direct Tool Usage

```
Use create_asset to create a hero image for a tech startup website
```

### With the Skill

The skill will proactively suggest image generation when:
- Building websites with hero sections
- Creating presentations
- Working with placeholder images
- Developing marketing materials

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GEMINI_API_KEY` | Yes | - | Your Gemini API key |
| `GEMINI_DEFAULT_MODEL` | No | `gemini-3-pro-image-preview` | Default model to use |
| `IMAGE_OUTPUT_DIR` | No | `./generated-images` | Where to save images |
| `GEMINI_REQUEST_TIMEOUT_MS` | No | `60000` | Timeout for Gemini requests |
| `MEDIA_PIPELINE_LOG_LEVEL` | No | `info` | Stderr logging level |

### Models

Available image models are fetched dynamically from the Gemini API at runtime. The CLI and MCP tool validate model choices against the current image-capable model list, and `GEMINI_DEFAULT_MODEL` is used when available.

### Aspect Ratios

| Ratio | Best For |
|-------|----------|
| `1:1` | Social media, thumbnails |
| `16:9` | Hero images, presentations |
| `9:16` | Mobile stories, vertical banners |
| `4:3` | Blog posts, general web |
| `3:2` | Photography-style images |

## Prompt Tips

Use this formula for effective prompts:

```
[Style] [Subject] [Composition] [Context/Atmosphere]
```

Example:
```
Minimalist 3D illustration of abstract geometric shapes floating in space,
soft gradient background from deep purple to electric blue, subtle glow effects,
modern professional aesthetic, wide composition for website header
```

See [skills/image-generation/references/prompt-crafting.md](https://github.com/guinacio/claude-image-gen/blob/HEAD/skills/image-generation/references/prompt-crafting.md) for advanced techniques.

## Architecture

### Two Execution Modes

**CLI Mode (Default)** - Used by the skill:
```
Claude → Skill → Bash → bundled CLI → Gemini API
```
- No MCP protocol overhead
- Skill runs bundled CLI directly
- All dependencies bundled in a single file

**MCP Mode (Optional)** - For direct tool calls:
```
Claude → MCP Tool → bundled MCP server → Gemini API
```
- Standard MCP protocol
- Useful for non-skill workflows
- Extension package only needs bundled entry points

### Abstract MCP Naming

The MCP server uses intentionally abstract naming (`media-pipeline` / `create_asset`) rather than image-specific names (`gemini-image-gen` / `generate_image`).

**Why?** When tool names directly match intent (e.g., "I need to generate an image" → `generate_image`), AI assistants tend to call the MCP tool directly, bypassing the skill layer. By using generic names:

- The **skill** (`image-generation`) becomes the semantically obvious choice for image tasks
- The **MCP tool** doesn't immediately register as the solution
- The skill's prompt optimization and aspect ratio selection are properly utilized

This is a form of prompt engineering for tool selection—making the abstraction layer the natural choice while the underlying implementation has a name that doesn't invite direct use.

## Project Structure

```
claude-image-gen/
├── .claude-plugin/       # Plugin configuration
│   ├── plugin.json       # Plugin manifest
│   └── marketplace.json  # Marketplace distribution
├── mcp-server/           # Server and CLI implementation
│   ├── src/
│   │   ├── index.ts      # MCP server entry point
│   │   ├── cli.ts        # CLI entry point (skill uses this)
│   │   ├── gemini-client.ts
│   │   ├── image-storage.ts
│   │   └── types.ts
│   ├── build/
│   │   ├── bundle.js     # Bundled MCP server
│   │   └── cli.bundle.js # Bundled CLI (all deps included)
│   ├── .mcpbignore       # Package only the runtime files needed by the bundle
│   ├── manifest.json     # MCPB extension manifest
│   ├── icon.png          # Extension icon
│   ├── package.json
│   └── tsconfig.json
├── skills/               # Claude skills
│   └── image-generation/
│       ├── SKILL.md      # Skill instructions (uses CLI)
│       └── references/
├── .mcp.json            # MCP configuration
└── README.md
```

## License

MIT