# Image MCP Server - Complete Documentation

> Standardized image generation interface for AI agents via Model Context Protocol (MCP)

## What is Image MCP?

Image MCP is a hosted Model Context Protocol (MCP) server that provides AI agents with the ability to generate images from text prompts. It abstracts away the complexity of managing multiple image generation APIs and provides a unified, standardized interface that any MCP-compatible client can use.

## Key Features

1. **Simple Setup**: Add the endpoint URL with your API key. No SDK installations.
2. **Multiple Models**: Access to cutting-edge image generation models through a single interface.
3. **CDN-Backed Storage**: Generated images are automatically uploaded to a CDN for fast global access.
4. **MCP Standard**: Uses the Model Context Protocol for seamless integration with AI tools.
5. **Stateless**: Each request is independent, no session management required.

## Authentication

Image MCP requires an API key for authentication. Get your API key from https://imagemcp.io/dashboard/keys

- **Header**: Authorization: Bearer YOUR_API_KEY
- **Credits**: Each image generation costs 10 credits
- **New accounts** receive free credits to get started

## Integration Guide

### For Cursor

Add to your `.cursor/mcp.json` or Cursor settings:

```json
{
  "mcpServers": {
    "image-mcp": {
      "url": "https://imagemcp.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### For Claude Desktop (CLI)

Run this command:

```bash
claude mcp add --transport http --header "Authorization: Bearer YOUR_API_KEY" image-mcp https://imagemcp.io/api/mcp
```

### For Custom MCP Clients

Connect to `https://imagemcp.io/api/mcp` using Streamable HTTP transport with Authorization header.

## API Reference

### Endpoint

- **URL**: `https://imagemcp.io/api/mcp`
- **Protocol**: Model Context Protocol (MCP)
- **Transport**: Streamable HTTP
- **Method**: POST
- **Content-Type**: application/json
- **Authentication**: Bearer token (API key required)

### Tools

#### generate_image

The primary tool for generating images.

**Input Schema (JSON):**
```json
{
  "prompt": {
    "type": "string",
    "description": "Text prompt describing the image to generate",
    "required": true
  },
  "model": {
    "type": "string",
    "description": "Model ID to use for generation",
    "required": false,
    "default": "google/gemini-3-pro-image-preview"
  }
}
```

**Example Call:**
```json
{
  "name": "generate_image",
  "arguments": {
    "prompt": "A serene Japanese garden with cherry blossoms, koi pond, and traditional wooden bridge, soft morning light",
    "model": "google/gemini-3-pro-image-preview"
  }
}
```

**Success Response:**
```json
{
  "content": [{
    "type": "text",
    "text": "{"url":"https://cdn.../generated/1234-abc.png","model":"google/gemini-3-pro-image-preview","prompt":"A serene Japanese garden...","filename":"1234-abc.png"}"
  }]
}
```

**Error Response:**
```json
{
  "content": [{
    "type": "text",
    "text": "{"error":"Error message here","model":"...","prompt":"..."}"
  }],
  "isError": true
}
```

### Models

| Model ID | Name | Description |
|----------|------|-------------|
| google/gemini-3-pro-image-preview | Gemini 3 Pro Image Preview | Google's latest multimodal model with image generation (default) |
| openai/gpt-5-image | GPT-5 Image | OpenAI's latest image generation model |
| black-forest-labs/flux.2-flex | FLUX.2 Flex | Black Forest Labs flexible diffusion model |
| black-forest-labs/flux.2-pro | FLUX.2 Pro | Black Forest Labs professional diffusion model |
| google/gemini-2.5-flash-image | Gemini 2.5 Flash Image | Google's fast multimodal image model |

### Prompts

#### generate-image

A basic prompt template for image generation.

**Arguments:**
- `description` (string, required): User's description of the desired image

**Usage:**
The prompt constructs: "Generate an image: {description}"

#### generate-image-detailed

An advanced prompt template with style parameters.

**Arguments:**
- `subject` (string, required): Main subject of the image
- `style` (string, optional): Art style (e.g., "photorealistic", "cartoon", "oil painting", "watercolor", "digital art")
- `mood` (string, optional): Mood or atmosphere (e.g., "dramatic", "peaceful", "vibrant", "mysterious", "romantic")
- `lighting` (string, optional): Lighting conditions (e.g., "sunset", "studio", "neon", "natural", "dramatic")

**Usage:**
Constructs a detailed prompt combining all provided parameters.

### Resources

#### mcp://image-mcp/models

Returns a JSON list of all available models.

**Response Format:**
```json
{
  "models": [
    { "id": "google/gemini-3-pro-image-preview", "name": "Gemini 3 Pro Image Preview" },
    { "id": "openai/gpt-5-image", "name": "GPT-5 Image" },
    ...
  ]
}
```

## Best Practices for AI Agents

### Prompt Engineering Tips

1. **Be Specific**: Include details about subject, style, composition, lighting, and mood.
2. **Use Art Terms**: Terms like "high contrast", "bokeh", "rule of thirds" improve results.
3. **Specify Format**: Mention if you want "portrait", "landscape", "square", "wide angle", etc.
4. **Include Context**: Add environment details like "in a forest", "urban setting", "at sunset".

### Example Prompts

**Portrait Photography:**
"Professional headshot of a confident business executive, studio lighting, neutral gray background, sharp focus, 85mm lens look"

**Landscape Art:**
"Majestic mountain range at golden hour, oil painting style, dramatic clouds, snow-capped peaks reflecting in a still alpine lake"

**Product Visualization:**
"Minimalist wireless earbuds floating on gradient background, soft shadows, product photography, clean aesthetic, 4K render"

**Fantasy Art:**
"Ancient dragon perched on crystal spire, bioluminescent scales, ethereal mist, epic fantasy art style, dramatic lighting from below"

## Technical Details

### Infrastructure

- **Image Storage**: DigitalOcean Spaces (S3-compatible)
- **CDN**: Global edge caching for fast image delivery
- **Compute**: Serverless functions for scalability
- **Models**: Accessed via OpenRouter API aggregation

### Response Times

- Average generation: 5-15 seconds depending on model
- CDN delivery: <100ms globally

### Rate Limits

- Currently no strict rate limits
- Fair use policy applies
- Contact for high-volume needs

## Error Handling

Common errors and solutions:

| Error | Cause | Solution |
|-------|-------|----------|
| "Authentication required" | Missing or invalid API key | Get your API key from Dashboard |
| "Insufficient credits" | Not enough credits for generation | Purchase more credits |
| "No image URL found in response" | Model failed to generate | Try a different model or simplify prompt |
| "OpenRouter API error: 429" | Rate limited | Wait and retry |
| "OpenRouter API error: 500" | Model service issue | Try a different model |

## IDE Integration Guides

Image MCP works with all major AI coding tools. Here are quick links to setup guides:

### Cursor
The most popular AI code editor. Add Image MCP in settings or .cursor/mcp.json.
Guide: https://imagemcp.io/connect/cursor

### Claude Code
Anthropic's official CLI. One command setup.
Guide: https://imagemcp.io/connect/claude-code
Command: `claude mcp add --transport http image-mcp https://imagemcp.io/api/mcp`

### Windsurf
Codeium's AI-native IDE. Configure in settings.
Guide: https://imagemcp.io/connect/windsurf

### Cline (VS Code)
Popular VS Code AI extension. Add to extension settings.
Guide: https://imagemcp.io/connect/cline

### Zed
High-performance editor with built-in AI. Configure in settings.json.
Guide: https://imagemcp.io/connect/zed

### VS Code with Continue
Open-source AI extension. Add to ~/.continue/config.json.
Guide: https://imagemcp.io/connect/vscode

### Roo Code
AI coding assistant. Standard MCP configuration.
Guide: https://imagemcp.io/connect/roo-code

## Support & Links

- **Website**: https://imagemcp.io
- **All Integrations**: https://imagemcp.io/connect
- **Documentation**: https://imagemcp.io/docs
- **OpenAPI Specification**: https://imagemcp.io/api/openapi
- **AI Plugin Manifest**: https://imagemcp.io/.well-known/ai-plugin.json

## Changelog

### v0.1.0 (Current)
- Initial release
- 5 image generation models
- Automatic CDN upload
- Basic and detailed prompt templates
- Model discovery resource