MCP MediaCrea - Image Generation Server

What is the Model Context Protocol?

MediaCrea exposes Gemini 2.5 Flash Image capabilities through the Model Context Protocol (MCP)—an open-source standard that connects AI applications to external tools, data, or workflows in a consistent way. MCP acts like a USB-C port for AI assistants: hosts such as Claude Code or Cursor can attach this server to generate, edit, and blend images without bespoke integrations. Each instance runs the MediaCrea presets by default for image-focused workflows. For a deeper understanding of MCP’s architecture and ecosystem benefits, see: Model Context Protocol – Getting Started.

Quick Start

1. Install (recommended: isolated virtual environment)

git clone https://github.com/YOU/mcp-mediacrea.git
cd mcp-mediacrea
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -e .

2. Configure credentials & output path

MediaCrea uses a simple configuration hierarchy:

• Environment variable (fastest):

  export GEMINI_API_KEY="YOUR_GEMINI_KEY"
  export MEDIACREA_OUTPUT_DIR="/absolute/path/for/images"  # optional

• Config file (portable default): create ~/.mediacrea_config.json so the server works across shells:

  cat > ~/.mediacrea_config.json <<'EOF'
  {
    "api_key": "YOUR_GEMINI_KEY",
    "output_dir": "~/mcp_generated_images"
  }
  EOF

3. (Optional) override per session

• GENAI_IMAGE_MODEL env var to pick a different Gemini image model (defaults to models/gemini-2.5-flash-image-preview).

• MEDIACREA_OUTPUT_DIR env var to change output folder (overrides config file).

4. Smoke test

mcp-mediacrea  # should start and wait on stdio; Ctrl+C to exit

Claude Code Configuration

Cursor / Claude Desktop (project .mcp.json)

{
  "mcpServers": {
    "nano-banana": {
      "type": "stdio",
      "command": "/usr/bin/env",
      "args": ["python3", "-m", "mcp_mediacrea"],
      "cwd": "/ABS/PATH/TO/mcp-mediacrea",
      "env": {
        "MEDIACREA_OUTPUT_DIR": "/ABS/PATH/TO/mcp_generated_images"
      }
    }
  }
}

You can swap command for mcp-mediacrea if the console script is on PATH (e.g. from the venv).

VS Code MCP extensions

Point the MCP entry at whichever interpreter/shell you use. Example:

{
  "type": "stdio",
  "command": "/ABS/PATH/TO/.venv/bin/mcp-mediacrea",
  "args": []
}

or equivalently the /usr/bin/env python3 -m mcp_mediacrea variant with cwd as above.

Tools (API)

generate_image

• Args: prompt (required), style?, aspect_ratio?, quality?

• Returns: { success, image_path, message, metadata } (base64 omitted by default)

Example:

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A banana wearing a superhero costume, studio lighting, 1:1",
    "style": "cartoon",
    "aspect_ratio": "1:1",
    "quality": "high"
  }
}

edit_image

• Args: image_path (required), instructions (required), preserve_style?

• Returns: { success, image_path, message, metadata }

Example:

{
  "name": "edit_image",
  "arguments": {
    "image_path": "/path/to/input.png",
    "instructions": "Increase contrast and add warm studio lighting",
    "preserve_style": true
  }
}

blend_images

• Args: image_paths (2–3 recommended), instructions, blend_mode?

• Returns: { success, image_path, message, metadata }

Example:

{
  "name": "blend_images",
  "arguments": {
    "image_paths": ["/img1.png", "/img2.png"],
    "instructions": "Merge seamlessly with natural lighting",
    "blend_mode": "natural"
  }
}

generate_text

• Args: prompt (required), system_instruction?, temperature?, max_output_tokens?

• Returns: { success, text, message, metadata }

Example:

{
  "name": "generate_text",
  "arguments": {
    "prompt": "Draft three taglines for a space-themed banana brand.",
    "system_instruction": "Keep each tagline under 12 words.",
    "temperature": 0.8
  }
}

Resources

• image://gallery/recent

• config://api/status (now includes active image and text models)

MCP Overview and Security

This server implements the Model Context Protocol (MCP) to expose tools, resources, and prompts over a standardized JSON-RPC transport (stdio). MCP allows hosts like IDEs or assistants to connect to external capabilities in a consistent way. See the official docs for details: Claude MCP docs, MCP Specification (2025‑06‑18).

Key considerations adapted from the spec:

• Users should explicitly consent to tool usage and understand what each tool does.

• Be mindful of data privacy when exposing resources; do not share sensitive paths or data without consent.

• Provide clear configuration (API keys, output directory) and visibility into side effects (where files are written).

Transport: stdio (recommended for portability). The console script mcp-mediacrea launches the server using stdio by default.

Configuration Reference

Environment variables:

• GEMINI_API_KEY: API key for Google GenAI (required if config file absent)

• GENAI_IMAGE_MODEL: image model id (default: models/gemini-2.5-flash-image-preview; other Gemini IDs will work as long as they support image generation)

• GENAI_TEXT_MODEL: text model id (default: models/gemini-2.5-flash; the server automatically falls back to other Gemini 2.x IDs if the first choice is unavailable)

• MEDIACREA_OUTPUT_DIR: absolute output directory (default: ../mcp_generated_images or ~/mcp_generated_images fallback)

Optional file: ~/.mediacrea_config.json

{ "api_key": "...", "output_dir": "/absolute/path" }

Example Workflows

Generate an image (tool call shape)

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A banana wearing a superhero costume",
    "style": "realistic",
    "aspect_ratio": "1:1",
    "quality": "high"
  }
}

Edit an image (tool call shape)

{
  "name": "edit_image",
  "arguments": {
    "image_path": "/path/to/input.png",
    "instructions": "Add a rainbow over the scene",
    "preserve_style": true
  }
}

Blend images (tool call shape)

{
  "name": "blend_images",
  "arguments": {
    "image_paths": ["/path/one.png", "/path/two.png"],
    "instructions": "Merge seamlessly with consistent lighting",
    "blend_mode": "natural"
  }
}

Generate text (tool call shape)

{
  "name": "generate_text",
  "arguments": {
    "prompt": "Summarise the mission of MediaCrea in two sentences",
    "system_instruction": "Adopt a friendly marketing tone",
    "max_output_tokens": 200
  }
}

Resource access

@image://gallery/recent
@config://api/status

Troubleshooting

• Tool response too large: If your client enforces strict size limits, keep base64 disabled (default). You can always fetch images from disk via the returned path or the recent gallery resource.

• Command not found: ensure your Python environment's bin is on PATH, then re‑install: pip install -e .

• No images saved: set an explicit model export GENAI_IMAGE_MODEL="models/gemini-2.5-flash-image-preview" or check access.

• Permission errors writing files: set MEDIACREA_OUTPUT_DIR to a writable location.

• Text output seems short: increase max_output_tokens or set GENAI_TEXT_MODEL to another accessible ID.

License

MIT