albumentations-mcp 1.0.2

MCP-compliant image augmentation server using Albumentations

Albumentations-MCP with Nano Banana (Gemini)

Natural language image augmentation via MCP protocol. Transform images using plain English with this MCP-compliant server built on Albumentations.

Example: "add blur and rotate 15 degrees" → Applies GaussianBlur + Rotate transforms automatically

Quick Start

# Install from PyPI
pip install albumentations-mcp

# Run as MCP server
uvx albumentations-mcp

MCP Client Setup

Claude Desktop

Copy claude-desktop-config.json to ~/.claude_desktop_config.json

Or add manually:

{
  "mcpServers": {
    "albumentations": {
      "command": "uvx",
      "args": ["albumentations-mcp"],
      "env": {
        "MCP_LOG_LEVEL": "INFO",
        "OUTPUT_DIR": "./outputs",
        "ENABLE_VISION_VERIFICATION": "true",
        "DEFAULT_SEED": "42"
      }
    }
  }
}

Kiro IDE

Copy kiro-mcp-config.json to .kiro/settings/mcp.json

Or add manually:

{
  "mcpServers": {
    "albumentations": {
      "command": "uvx",
      "args": ["albumentations-mcp"],
      "env": {
        "MCP_LOG_LEVEL": "INFO",
        "OUTPUT_DIR": "./outputs",
        "ENABLE_VISION_VERIFICATION": "true",
        "DEFAULT_SEED": "42"
      },
      "disabled": false,
      "autoApprove": ["augment_image", "list_available_transforms"]
    }
  }
}

Available Tools

• augment_image - Apply augmentations using natural language or presets
• list_available_transforms - Get supported transforms and parameters
• validate_prompt - Test prompts without processing images
• list_available_presets - Get available preset configurations
• set_default_seed - Set global seed for reproducible results
• get_pipeline_status - Check pipeline health and configuration
• get_quick_transform_reference - Condensed transform keywords for prompting
• get_getting_started_guide - Structured workflow guide for first-time assistants

VLM (Gemini “Nano Banana”) Tools

• check_vlm_config – Report readiness without exposing secrets
• vlm_generate_preview – Text→image preview for prompt/style ideation (no session)
• vlm_edit_image – Image‑conditioned edit; runs full session + verification
• vlm_suggest_recipe – Planning‑only: outputs Alb Compose + optional VLMEdit prompt template; can save under outputs/recipes/

VLM quickstart (env or file):

# Option 1: env
set ENABLE_VLM=true
set VLM_PROVIDER=google
set VLM_MODEL=gemini-2.5-flash-image-preview
set GOOGLE_API_KEY=...  # or GEMINI_API_KEY / VLM_API_KEY

# Option 2: file (auto‑discovered)
# Place a non‑secret file at config/vlm.json:
{
  "enabled": true,
  "provider": "google",
  "model": "gemini-2.5-flash-image-preview"
  // api_key may be in file or environment
}

Examples:

# Preview (no input image, no session)
vlm_generate_preview(prompt="Neon night street, cinematic moodboard")

# Edit (image + prompt, full session)
vlm_edit_image(
    image_path="examples/basic_images/cat.jpg",
    prompt=(
        "Using the provided photo of a cat, add a small, knitted wizard hat. "
        "Preserve identity, pose, lighting, and composition."
    ),
    edit_type="edit",
)

# Plan and save a hybrid recipe (Alb + VLMEdit)
plan = vlm_suggest_recipe(
    task="domain_shift",
    constraints_json='{"output_count":3,"identity_preserve":true}',
    save=True,
)
print(plan["paths"])  # outputs/recipes/<timestamp>_<task>_<hash>/

MCP env examples for VLM (choose one option)

Option A — file (preferred):

{
  "mcpServers": {
    "albumentations": {
      "command": "uvx",
      "args": ["albumentations-mcp"],
      "env": {
        "MCP_LOG_LEVEL": "INFO",
        "OUTPUT_DIR": "./outputs",
        "ENABLE_VLM": "true",
        "VLM_CONFIG_PATH": "config/vlm.json"
      }
    }
  }
}

Option B — inline env (no file):

{
  "mcpServers": {
    "albumentations": {
      "command": "uvx",
      "args": ["albumentations-mcp"],
      "env": {
        "MCP_LOG_LEVEL": "INFO",
        "OUTPUT_DIR": "./outputs",
        "ENABLE_VLM": "true",
        "VLM_PROVIDER": "google",
        "VLM_MODEL": "gemini-2.5-flash-image-preview"
      }
    }
  }
}

Available Prompts

• compose_preset - Generate augmentation policies from presets with optional tweaks
• explain_effects - Analyze pipeline effects in plain English
• augmentation_parser - Parse natural language to structured transforms
• vision_verification - Compare original and augmented images
• error_handler - Generate user-friendly error messages and recovery suggestions

Available Resources

• transforms_guide - Complete transform documentation with parameters and ranges
• policy_presets - Built-in preset configurations (segmentation, portrait, lowlight)
• available_transforms_examples - Usage examples and patterns organized by categories
• preset_pipelines_best_practices - Best practices guide for augmentation workflows
• troubleshooting_common_issues - Common issues, solutions, and diagnostic steps
• getting_started_guide - Same content as the tool version, resource-style

Usage Examples

# Simple augmentation
augment_image(
    image_path="photo.jpg",
    prompt="add blur and rotate 15 degrees"
)

# Using presets
augment_image(
    image_path="dataset/image.jpg",
    preset="segmentation"
)

# Test prompts
validate_prompt(prompt="increase brightness and add noise")

# Process from URL (two-step)
session = load_image_for_processing(image_source="https://example.com/image.jpg")
# Use the returned session_id from the previous call
augment_image(session_id="<session_id>", prompt="add blur and rotate 10 degrees")

Features

• Natural Language Processing - Convert English descriptions to transforms
• Preset Pipelines - Pre-configured transforms for common use cases
• Reproducible Results - Seeding support for consistent outputs
• MCP Protocol Compliant - Full MCP implementation with tools, prompts, and resources
• Comprehensive Documentation - Built-in guides, examples, and troubleshooting resources
• Production Ready - Comprehensive testing, error handling, and structured logging
• Multi-Source Input - Works with local file paths, base64 payloads, and URLs (via loader)

Documentation

• Installation & Setup
• Architecture Overview
• Purpose & Rationale
• Preset Configurations
• Session Folders (outputs/) Guide
• Regex Security Analysis
• Design Philosophy
• Usage Examples
• VLM (Nano Banana/Gemini) Guide
• Troubleshooting
• Contributing

Configuration Files

• Claude Desktop Config
• Kiro IDE Config
• All Configuration Examples
• VLM Example Config

License

MIT License - see LICENSE for details.

Contact: [e-mail]