Skip to main content
Glama

mcp-server-bedrock-image

CI PyPI Python 3.12+ License: MIT MCP

An MCP (Model Context Protocol) server that gives AI agents the ability to generate, edit, and manipulate images using Stability AI models on AWS Bedrock.

Connect it to Claude Code, Cursor, Windsurf, VS Code, or any MCP-compatible client — then ask your AI to generate images, remove backgrounds, transfer styles, upscale, and more.

Tools

Tool

What it does

Model

generate_image

High-quality text-to-image generation

Stable Image Ultra

generate_image_core

Faster, lower-cost generation

Stable Image Core

remove_background

Remove image background

Stability Remove Background v1

style_transfer

Apply style from a reference image

Stability Style Transfer v1

search_and_recolor

Recolor specific elements by description

Stability Search & Recolor v1

outpaint

Extend image in any direction

Stability Outpaint v1

search_and_replace

Find and replace objects in an image

Stability Search & Replace v1

upscale_fast

4x resolution upscale

Stability Fast Upscale v1

upscale_creative

Creative upscale up to 4K

Stability Creative Upscale v1

compose_branded

Composition-aware logo overlay

Local (Pillow — no Bedrock call)

Related MCP server: AWS Nova Canvas MCP Server

Quickstart

Prerequisites

Install & run

# Run directly (no install needed)
uvx mcp-server-bedrock-image

# Or install globally
uv tool install mcp-server-bedrock-image

Authentication

Two auth modes are supported:

boto3 mode (default) — Uses standard AWS credential chain (env vars, ~/.aws/credentials, IAM roles, STS):

export AWS_REGION=us-west-2

Bearer token mode — Uses Bedrock API keys (no AWS CLI setup needed):

export BEDROCK_AUTH_MODE=bearer
export AWS_BEARER_TOKEN_BEDROCK=your-api-key-here
export AWS_REGION=us-west-2

Client Configuration

Add to .claude/settings.json:

{
  "mcpServers": {
    "bedrock-image": {
      "command": "uvx",
      "args": ["mcp-server-bedrock-image"],
      "env": {
        "AWS_REGION": "us-west-2",
        "IMAGE_STORAGE_DIRECTORY": ".content-workspace/images"
      }
    }
  }
}

For bearer token auth, add "BEDROCK_AUTH_MODE": "bearer" and "AWS_BEARER_TOKEN_BEDROCK": "your-api-key" to the env block.

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bedrock-image": {
      "command": "uvx",
      "args": ["mcp-server-bedrock-image"],
      "env": {
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "bedrock-image": {
      "command": "uvx",
      "args": ["mcp-server-bedrock-image"],
      "env": {
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bedrock-image": {
      "command": "uvx",
      "args": ["mcp-server-bedrock-image"],
      "env": {
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

Environment Variables

Variable

Default

Description

AWS_REGION

us-west-2

AWS region for Bedrock

BEDROCK_AUTH_MODE

boto3

Auth mode: boto3 or bearer

AWS_BEARER_TOKEN_BEDROCK

—

Bedrock API key (bearer mode only)

BEDROCK_ENDPOINT

Auto from region

Override Bedrock runtime endpoint

IMAGE_STORAGE_DIRECTORY

/tmp/mcp-server-bedrock-image

Where to save generated images

SAVE_METADATA

true

Save JSON metadata alongside images

See .env.example for a template.

Usage Examples

Once connected, ask your AI agent naturally:

"Generate a hero image of a modern hotel lobby with warm lighting in 16:9"

"Remove the background from this product photo"

"Apply the style of this watercolor painting to the room photo"

"Add our logo to the generated image in the least busy corner"

Or call tools directly:

# Generate
generate_image(prompt="Modern hotel lobby with warm lighting", aspect_ratio="16:9")

# Edit
remove_background(image_path="/path/to/photo.png")
style_transfer(prompt="Watercolor style", image_path="room.png", style_image_path="ref.png")
search_and_replace(image_path="scene.png", prompt="red chair", search_prompt="blue chair")
outpaint(image_path="photo.png", prompt="extend the garden", right=200, bottom=100)

# Upscale
upscale_fast(image_path="/path/to/small.png")
upscale_creative(image_path="photo.png", prompt="enhance details, sharp textures")

# Brand
compose_branded(image_path="hero.png", logo_path="logo.png", output_path="branded.png")

How compose_branded works

The composition-aware branding tool doesn't use Bedrock — it runs locally with Pillow. It divides the image into a 3x3 grid, scores each quadrant by visual complexity (standard deviation of grayscale values), and places the logo in the least complex region. It also auto-selects between light and dark logo variants based on the background brightness.

Architecture

src/mcp_server_bedrock_image/
├── server.py          # FastMCP server — registers all 10 tools
├── config.py          # Environment variables and model IDs
├── bedrock_client.py  # Dual-auth Bedrock client (boto3 + bearer)
├── image_utils.py     # Image save and metadata utilities
└── tools/
    ├── generate.py    # Text-to-image generation
    ├── edit.py        # Background removal, style transfer, recolor, outpaint, search-replace
    ├── upscale.py     # Fast and creative upscaling
    └── compose.py     # Composition-aware logo placement

Development

# Clone and install
git clone https://github.com/Yaksh36/mcp-server-bedrock-image.git
cd mcp-server-bedrock-image
uv sync --all-extras --dev

# Run tests
uv run pytest -v

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Contributing

Contributions are welcome. Please:

  1. Fork the repo and create a feature branch

  2. Add tests for new functionality

  3. Ensure uv run pytest -v and uv run ruff check src/ tests/ pass

  4. Open a pull request

License

MIT

Available Tools

10 tools
compose_brandedC

Overlay logo with composition-aware placement.

Inputs: logo_path (required), image_path (required), output_path (required), logo_scale, +1 more.

generate_imageC

Generate a high-quality image using Stable Image Ultra on Bedrock.

Inputs: prompt (required), seed, filename, output_dir, +2 more.

generate_image_coreB

Generate an image using Stable Image Core (faster, lower cost).

Inputs: prompt (required), seed, filename, output_dir, +2 more.

outpaintB

Extend an image in any direction while maintaining visual consistency.

Inputs: prompt (required), image_path (required), top, left, +4 more.

remove_backgroundB

Remove the background from an image.

Inputs: image_path (required), filename, output_dir.

search_and_recolorC

Recolor specific elements in an image.

Inputs: prompt (required), image_path (required), select_prompt (required), recolor_prompt (required), +2 more.

search_and_replaceC

Replace objects or elements in an image.

Inputs: prompt (required), image_path (required), search_prompt (required), filename, +1 more.

style_transferC

Apply the style of a reference image to a source image.

Inputs: prompt (required), image_path (required), style_image_path (required), filename, +2 more.

upscale_creativeB

Creatively upscale image up to 4K resolution.

Inputs: prompt (required), image_path (required), filename, output_dir, +1 more.

upscale_fastC

Upscale image resolution by 4x.

Inputs: image_path (required), filename, output_dir.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct image operation: generation, editing, style transfer, upscaling, etc. The two generation tools are clearly differentiated by model (Ultra vs Core) and trade-off (quality vs speed), so there is no real ambiguity.

    Naming Consistency4/5

    Most names follow a verb_noun or verb_adverb pattern in snake_case (e.g., generate_image, remove_background, upscale_fast). 'outpaint' is a slight deviation as a single verb, but it's still intuitive and consistent with the action-oriented style.

    Tool Count5/5

    With 10 tools, the server is well-scoped for an image generation/editing toolkit. Each tool covers a separate capability with no unnecessary redundancy, making the count feel justified and manageable.

    Completeness5/5

    The toolkit covers the core image lifecycle: generation, editing (style, recolor, replace, background removal), extension (outpaint), enhancement (upscaling), and branding (compose_branded). No critical gaps are apparent for its intended purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers