mcp-media-toolkit

mcp-media-toolkit

Generate AI images with Google Gemini (Nano Banana) and upload them to any S3-compatible storage — in a single MCP tool call.

A batteries-included MCP (Model Context Protocol) server that works in any MCP client (Claude Code, Cursor, Codex, Cline, Continue, Windsurf, …) and doubles as a Claude Code plugin with guided skills and automatic prompt optimization.

Features

• Image generation — full Nano Banana family: gemini-2.5-flash-image (fast, 1K), gemini-3.1-flash-image-preview (Nano Banana 2, 2K), and gemini-3-pro-image-preview (Nano Banana Pro, 4K).
• S3-compatible upload — works with Cloudflare R2, AWS S3, MinIO, DigitalOcean Spaces, and any other S3-protocol service.
• One-shot workflow — a dedicated generate_and_upload tool goes from prompt to public URL in a single call.
• Automatic prompt optimization — the Claude Code skills rewrite casual descriptions into rich, detailed prompts so short requests still produce great images.
• Partial-failure recovery — if generation succeeds but upload fails, the local file is preserved and reported.
• Clear error messages — configuration and runtime errors are designed to be acted on without reading source code.
• Dual distribution — use it as an npm package via npx in any MCP client, or install it as a Claude Code plugin for the extra skills.

Quick Start

# 1. Set environment variables (see Configuration below)
export GEMINI_API_KEY="your-key"
export S3_ENDPOINT="https://..."
export S3_ACCESS_KEY_ID="..."
export S3_SECRET_ACCESS_KEY="..."
export S3_BUCKET="media"
export S3_PUBLIC_URL="https://media.example.com"

# 2. Add to your MCP client config (Claude Code, Cursor, etc.)
#    See Installation section for exact snippets.

# 3. Ask your agent to generate an image — you get back a public URL.

Installation

As an MCP server (any MCP client)

Add to your MCP client configuration. The server is distributed as an npm package, so npx handles installation on the fly.

Claude Code — add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "mcp-media-toolkit": {
      "command": "npx",
      "args": ["-y", "mcp-media-toolkit"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key",
        "S3_ENDPOINT": "https://<account>.r2.cloudflarestorage.com",
        "S3_ACCESS_KEY_ID": "your-access-key",
        "S3_SECRET_ACCESS_KEY": "your-secret-key",
        "S3_BUCKET": "media",
        "S3_PUBLIC_URL": "https://media.example.com",
        "S3_REGION": "auto"
      }
    }
  }
}

Cursor — add to ~/.cursor/mcp.json with the same shape as above.

Codex / Cline / Continue / Windsurf — consult your client's MCP config docs. The command is npx -y mcp-media-toolkit with environment variables passed in the env block.

As a Claude Code plugin (with skills)

The Claude Code plugin adds three slash-command skills on top of the MCP tools — the skills optimize prompts automatically and guide the workflow.

# Via the Claude Code marketplace (once published)
claude plugin add tadeukaiba/mcp-media-toolkit

Or clone the repository and point Claude Code at it manually.

Global npm install

If you prefer a global install over npx:

npm install -g mcp-media-toolkit

Then reference mcp-media-toolkit directly as the command in your MCP config instead of npx.

Configuration

All configuration is done via environment variables. The server validates everything at startup and reports any issue with a clear, actionable message.

Environment variables

Variable	Required	Description	Example
GEMINI_API_KEY	Yes	Google AI Studio API key. Get one free at aistudio.google.com/apikey.	AIza...
S3_ENDPOINT	For upload	Endpoint URL of your S3-compatible storage.	https://abc123.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID	For upload	S3 access key ID.	AKIA...
S3_SECRET_ACCESS_KEY	For upload	S3 secret access key.	abc123...
S3_BUCKET	For upload	Bucket name.	media
S3_PUBLIC_URL	For upload	Public base URL where uploads are accessible. No trailing slash.	https://media.example.com
S3_REGION	Optional	Region name. Defaults to auto.	auto, us-east-1
IMAGE_OUTPUT_DIR	Optional	Directory for generated images. Defaults to ~/Pictures/mcp-media/.	/tmp/images