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)

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

Claude Code Configuration

Cursor / Claude Desktop (project .mcp.json)

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:

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:

edit_image

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

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

Example:

blend_images

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

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

Example:

generate_text

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

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

Example:

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

Example Workflows

Generate an image (tool call shape)

Edit an image (tool call shape)

Blend images (tool call shape)

Generate text (tool call shape)

Resource access

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