Amazon Bedrock Image Generation MCP Server

Note: This is a community-maintained fork of awslabs/mcp/bedrock-image-mcp-server with additional features and improvements. Original work by Amazon Web Services under Apache 2.0 license.

MCP server for generating and editing images using Stable Diffusion 3.5 Large, Stable Image Ultra and Core, and Stability AI Image Services through Amazon Bedrock.

Which model should I use?

Three Stability AI text-to-image models form a quality ladder, all in us-west-2:

In short: generate_image_ultra for a few premium, large-format or print pieces; generate_image_sd35 when you need many good assets; generate_image_core when speed and cost dominate. Stability credits only Ultra with typography, so prefer it when the image contains text.

All quotes are Stability AI's own words, from their Bedrock launch post and their API specification (api.stability.ai/v2alpha/openapi). Credits are Stability's billing unit — on Bedrock you are billed per image by AWS, so treat them as a cost ratio, not a price.

For image-to-image, transform_image_sd35 is the only option of the four; Ultra and Core are text-to-image only.

On seeds: a fixed non-zero seed reproduces the same image reliably within a short window (verified 6/6 identical), but is best-effort rather than guaranteed — repeats separated by longer intervals occasionally differ, which appears to be Bedrock serving the request from a different backend. Use seed=0 for explicitly random output.

Features

Stability AI Text-to-Image (4 tools)

Highest quality

• Generate images with generate_image_ultra (Stable Image Ultra)
• Stability AI's flagship model: best photorealism, lighting and legible text
• Same aspect ratios and prompt length as SD3.5; higher cost per image
• Text-to-image only, png or jpeg output (no webp)

Fastest and cheapest

• Generate images with generate_image_core (Stable Image Core)
• Lowest cost and latency; ideal for drafts and iterating on concepts
• Text-to-image only, png or jpeg output (no webp)

Balanced text-to-image generation

• Generate images from text prompts with generate_image_sd35
• Supports prompts up to 10,000 characters
• 9 aspect ratio options: 16:9, 1:1, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21
• Superior prompt adherence and detail preservation
• Seed support for reproducible results (0-4,294,967,294)

Image-to-image transformation

• Transform existing images with transform_image_sd35
• Strength parameter (0.0-1.0) controls transformation intensity
• Supports file paths and base64 image inputs
• All text-to-image parameters available

Stability AI Upscale Services (3 tools)

Creative upscaling

• Upscale images to 4K with AI enhancement using upscale_creative
• 20-40x upscale from low-resolution inputs (64x64 to 1MP)
• Creativity parameter (0.1-0.5) controls enhancement level
• Style preset support for specific aesthetics

Conservative upscaling

• Upscale to 4K while preserving details with upscale_conservative
• Supports inputs up to 9.4 megapixels, aspect ratio 1:2.5 to 2.5:1
• Minimal alterations to original image

Fast upscaling

• Quick 4x upscaling with upscale_fast
• Fast processing for quick resolution increases
• Supports inputs from 32px to 1,536px per side, up to 1MP

Stability AI Edit Services (6 tools)

Inpainting (Generative Fill)

• Fill masked regions with AI content using inpaint_image
• Grayscale mask support (white=fill, black=preserve)
• grow_mask parameter (0-20) for edge blending

Outpainting

• Extend images beyond boundaries with outpaint_image
• Directional expansion: left, right, up, down (0-2000 pixels each)
• Creativity parameter for extension style

Search and Replace

• Find and replace objects with search_and_replace
• Automatic object detection and masking
• No manual mask required

Search and Recolor

• Recolor specific objects with search_and_recolor
• Preserves structure while changing colors
• Maintains image quality

Remove Object

• Remove unwanted objects with remove_object
• Context-aware filling of removed areas
• Seamless blending with surroundings

Remove Background

• Automatic background removal with remove_background
• Returns PNG with transparency
• Handles complex subjects (hair, transparent objects)

Stability AI Control Services (4 tools)

Sketch to Image

• Convert sketches to detailed images with sketch_to_image
• control_strength parameter (0.0-1.0)
• Preserves sketch structure while adding detail

Structure Control

• Generate images from structural guides with structure_control
• Follows edge maps and structural guidance
• control_strength for adherence level

Style Guide

• Match reference image style with style_guide
• fidelity parameter (0.0-1.0) for style matching
• Accepts prompts for content description

Style Transfer

• Transfer style between images with style_transfer
• Fine-grained control: composition_fidelity, style_strength, change_strength
• Requires init_image (content) and style_image (style reference)

Mask Creation Utilities (3 tools)

Create masks programmatically for use with inpaint_image and remove_object tools. Masks are grayscale images where white pixels indicate areas to fill/remove and black pixels indicate areas to preserve.

Rectangular Mask

• Create rectangular masks with create_rectangular_mask
• Configurable position (x, y) and size (width, height)
• Optional feathering (0-50 pixels) for soft edges
• Perfect for signs, windows, rectangular objects

Ellipse Mask

• Create elliptical/circular masks with create_ellipse_mask
• Configurable center point and radii
• Optional feathering for soft edges
• Ideal for faces, balls, wheels, organic shapes

Full Mask

• Create full white masks with create_full_mask
• Covers entire image
• Useful for testing and full-image replacement

Workspace Integration

• All images saved to user-specified workspace directories with automatic folder creation
• Support for multiple output formats (PNG, JPEG, WebP)
• Unique filename generation or custom naming

AWS Authentication

• Uses AWS profiles for secure access to Amazon Bedrock services
• Supports all AWS regions where Bedrock models are available

Prerequisites

1. Install uv from Astral or the GitHub README
2. Install Python using uv python install 3.10
3. Set up AWS credentials with access to Amazon Bedrock
   • You need an AWS account with Amazon Bedrock enabled
   • Configure AWS credentials with aws configure or environment variables
   • Ensure your IAM role/user has the required permissions (see AWS IAM Permissions below)

Installation

Cursor	VS Code

Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit ~/.aws/amazonq/mcp.json):

Pick your region deliberately. The examples below use us-west-2, which is also the default when AWS_REGION is unset. It is the only region carrying the recommended text-to-image models (Ultra, Core and SD3.5) and it also serves all 13 Stability edit/upscale/control tools, so every tool works there. See Supported AWS Regions.

{
  "mcpServers": {
    "bedrock-image-mcp-server": {
      "command": "uvx",
      "args": ["bedrock-image-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows Installation

For Windows users, the MCP server configuration format is slightly different:

{
  "mcpServers": {
    "bedrock-image-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "bedrock-image-mcp-server@latest",
        "bedrock-image-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

or docker after a successful docker build -t bedrock-image-mcp-server .:

# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

  {
    "mcpServers": {
      "bedrock-image-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "--interactive",
          "--env",
          "AWS_REGION=us-west-2",
          "--env",
          "FASTMCP_LOG_LEVEL=ERROR",
          "--env-file",
          "/full/path/to/file/above/.env",
          "bedrock-image-mcp-server:latest"
        ],
        "env": {},
        "disabled": false,
        "autoApprove": []
      }
    }
  }

NOTE: Your credentials will need to be kept refreshed from your host

Installing via Smithery

To install Amazon Bedrock Image MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install bedrock-image-mcp-server --client claude

AWS Authentication

The MCP server uses the AWS profile specified in the AWS_PROFILE environment variable. If not provided, it defaults to the "default" profile in your AWS configuration file.

"env": {
  "AWS_PROFILE": "your-aws-profile",
  "AWS_REGION": "us-west-2"
}

Make sure the AWS profile has permissions to access Amazon Bedrock and the image generation models. The MCP server creates a boto3 session using the specified profile to authenticate with AWS services. Your AWS IAM credentials remain on your local machine and are strictly used for using the Amazon Bedrock model APIs.

Usage Examples

Stability AI Text-to-Image (start here)

Highest quality

# Stable Image Ultra: final assets, best text rendering
generate_image_ultra(
    prompt="A weathered brass compass on an antique nautical chart, macro photo",
    aspect_ratio="3:2",
    output_format="png"   # png or jpeg only; webp is not supported
)

Fastest draft

# Stable Image Core: quick concepts to iterate on
generate_image_core(
    prompt="Three flat vector logo concepts for a coffee shop",
    aspect_ratio="1:1"
)

Balanced default

generate_image_sd35(
    prompt="A serene mountain landscape at sunset",
    aspect_ratio="1:1"
)

Text-to-Image with Long Prompt

# SD3.5 supports up to 10,000 character prompts
generate_image_sd35(
    prompt="A detailed cyberpunk cityscape at night with neon signs, flying cars, holographic advertisements, rain-slicked streets reflecting colorful lights, towering skyscrapers with intricate architectural details, bustling crowds of people with futuristic fashion, street vendors with glowing food stalls, and a massive digital billboard displaying animated content",
    aspect_ratio="16:9",
    negative_prompt="blurry, low quality, distorted",
    seed=42
)

Image-to-Image Transformation

# Transform an existing image
transform_image_sd35(
    prompt="Transform into a watercolor painting style",
    image="/path/to/image.jpg",
    strength=0.7,
    aspect_ratio="1:1"
)

Stability AI Upscale Services

Creative Upscaling

# Upscale with AI enhancement
upscale_creative(
    image="/path/to/low_res_image.jpg",
    prompt="A professional portrait photograph",
    creativity=0.3,
    style_preset="photographic"
)

Conservative Upscaling

# Upscale preserving original details
upscale_conservative(
    image="/path/to/image.jpg",
    prompt="Product photography"
)

Fast Upscaling

# Quick 4x upscale
upscale_fast(
    image="/path/to/image.jpg"
)

Stability AI Edit Services

Inpainting

# Fill masked region
inpaint_image(
    image="/path/to/image.jpg",
    mask="/path/to/mask.png",
    prompt="A red sports car",
    grow_mask=5
)

Outpainting

# Extend image boundaries
outpaint_image(
    image="/path/to/image.jpg",
    prompt="Continue the landscape",
    left=500,
    right=500,
    creativity=0.5
)

Search and Replace

# Replace objects without manual masking
search_and_replace(
    image="/path/to/image.jpg",
    search_prompt="old wooden chair",
    prompt="modern leather armchair"
)

Search and Recolor

# Recolor specific objects
search_and_recolor(
    image="/path/to/image.jpg",
    select_prompt="the car",
    prompt="bright red color"
)

Remove Object

# Remove unwanted objects
remove_object(
    image="/path/to/image.jpg",
    mask="/path/to/object_mask.png"
)

Remove Background

# Automatic background removal
remove_background(
    image="/path/to/image.jpg"
)

Stability AI Control Services

Sketch to Image

# Convert sketch to detailed image
sketch_to_image(
    sketch="/path/to/sketch.jpg",
    prompt="A realistic portrait of a person",
    control_strength=0.7
)

Structure Control

# Generate from structural guide
structure_control(
    control_image="/path/to/edge_map.jpg",
    prompt="A modern building facade",
    control_strength=0.8
)

Style Guide

# Match reference style
style_guide(
    reference_image="/path/to/style_ref.jpg",
    prompt="A mountain landscape",
    fidelity=0.5
)

Style Transfer

# Transfer style with fine control
style_transfer(
    init_image="/path/to/content.jpg",
    style_image="/path/to/style.jpg",
    prompt="Apply artistic style",
    composition_fidelity=0.9,
    style_strength=1.0,
    change_strength=0.9
)

AWS IAM Permissions

Your AWS IAM user or role needs the following permissions to use this MCP server:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel"
            ],
            "Resource": [
                "arn:aws:bedrock:*::foundation-model/stability.sd3-5-large-v1:0",
                "arn:aws:bedrock:*::foundation-model/stability.stable-image-ultra-v1:1",
                "arn:aws:bedrock:*::foundation-model/stability.stable-image-core-v1:1",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-creative-upscale-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-conservative-upscale-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-fast-upscale-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-inpaint-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-outpaint-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-search-replace-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-search-recolor-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-erase-object-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-remove-background-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-control-sketch-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-control-structure-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-image-style-guide-v1:0",
                "arn:aws:bedrock:*::foundation-model/us.stability.stable-style-transfer-v1:0"
            ]
        }
    ]
}

Supported AWS Regions

Region coverage differs between the model families. us-west-2 is the only region that runs every tool. Pick your AWS_REGION based on which tools you need.

Practical consequences:

• us-west-2 is the default, and the only region where all 20 tools work: the four SD3.5/Ultra/Core tools, all 13 Stability edit/upscale/control tools, and the 3 local mask helpers.
• us-east-1 and us-east-2 are strict subsets — identical to each other in image-model coverage, and missing all four text-to-image tools.

The Stability AI tools are invoked through US Geo cross-region inference profiles (their model IDs carry a us. prefix), so a request sent to any of the three regions may be served from another one. The underlying in-region model IDs are not enabled for direct on-demand use.

Nova Canvas was removed

AWS retired Amazon Nova Canvas on 2026-09-30, and every request to it now fails, so version 0.5.0 removed the generate_image and generate_image_with_colors tools. Use generate_image_sd35 (or generate_image_ultra / generate_image_core) in us-west-2 instead. There is no colour-palette parameter on these models: name the colours in the prompt. For several images, call the tool several times.

Note: verified against both the Bedrock API (GetFoundationModel lifecycle status) and the AWS model cards. Availability changes, so check your own region with:

aws bedrock list-foundation-models --region us-west-2 \
  --query "modelSummaries[?contains(modelId,'stability')].[modelId,modelLifecycle.status]"

See the AWS regional availability by model and model lifecycle pages for the authoritative lists.

Troubleshooting

Common Issues

"Model not found" or "Access denied" errors

Problem: You receive errors indicating the model is not available or you don't have access.

Solutions:

1. Verify your AWS region supports the model you're trying to use (see Supported AWS Regions). The provided model identifier is invalid almost always means the model is not in your region — most often SD3.5, which is us-west-2 only.
2. Ensure you've requested model access in the AWS Bedrock console:
   • Go to AWS Bedrock console → Model access
   • Request access for the models you want to use
   • Wait for approval (usually instant for most models)
3. Verify your IAM permissions include bedrock:InvokeModel for the specific model ARN

"Response payload size exceeds limit" (all three upscale tools)

Problem: an upscale tool fails with {"detail":"Response payload size NNNNNNNN bytes exceeds the maximum allowed size of 16777216 bytes"}.

Cause: this is a limit on output size, not on format support. Bedrock returns the image base64-encoded inside the JSON response and caps that response at 16MB, so the practical ceiling is roughly a 12MB image. Ordinary generation is ~2MB and never comes close; upscaling returns 3K-4K images, where a PNG is 20-35MB. It is an API limit, not a bug in this server.

PNG is supported and is the default for every tool except upscale_creative, which defaults to JPEG because its PNG output never fits. Elsewhere PNG is the default for the case most likely to exceed the cap — a full-size upscale.

Solution: request output_format="jpeg" or "webp" for full-size upscales. Measured on a 1MP input:

PNG does work when the output is small enough, because for upscale_fast and upscale_conservative the output scales with the input — a 256x256 input gave a 1.4MB PNG from fast and a 9.9MB PNG from conservative, and 512x512 gave a 5.9MB PNG from fast. upscale_creative is the exception: its output is a fixed ~3150x3150 whatever you feed it, so no input size makes PNG work there.

"Invalid image dimensions" errors

Problem: Image generation fails with dimension validation errors.

Solutions:

• SD3.5: Use one of the supported aspect ratios (16:9, 1:1, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21)
• Upscale services: Check input image size constraints:
  • Creative: 64px per side minimum, up to 1MP
  • Fast: 32-1,536px per side, up to 1MP
  • Conservative: 64px per side minimum, up to 9.4MP, aspect ratio 1:2.5 to 2.5:1

"Content filtered" responses

Problem: Your generated image is blocked by content filtering.

Solutions:

1. Review your prompt for potentially sensitive content
2. Use negative prompts to exclude problematic elements
3. Adjust your prompt to be more specific and less ambiguous
4. Try different seed values

Mask validation errors (Inpainting/Remove Object)

Problem: Mask image is rejected during inpainting or object removal.

Solutions:

1. Ensure mask is grayscale (not RGB or RGBA)
2. Verify mask dimensions exactly match the input image
3. Use white (255) for areas to fill/remove, black (0) for areas to preserve
4. Save mask as PNG or JPEG format

"Image too large" warnings (Upscaling)

Problem: Warning about input image being too large for creative upscaling.

Solutions:

1. Use upscale_conservative instead for larger images (up to 9.4MP) — it is the only one of the three that accepts inputs above 1MP
2. Resize your input image to under 1MP before creative upscaling
3. Note that upscale_fast has the same 1MP input cap as creative upscaling, so it is not a workaround for an oversized input

AWS credentials not found

Problem: Server fails to start with AWS credential errors.

Solutions:

1. Run aws configure to set up your credentials
2. Set AWS_PROFILE environment variable to your profile name
3. Verify credentials file exists at ~/.aws/credentials
4. For temporary credentials, ensure AWS_SESSION_TOKEN is also set

Slow image generation

Problem: Image generation takes longer than expected.

Solutions:

1. This is normal - AI image generation can take 10-60 seconds depending on:
   • Model complexity (SD3.5 and upscaling are slower)
   • Image resolution
   • AWS region latency
2. Use upscale_fast instead of creative upscaling for faster results
3. Consider using a closer AWS region

File path issues

Problem: Images not found or saved to unexpected locations.

Solutions:

1. Use absolute file paths for input images
2. Specify workspace_dir parameter to control output location
3. Check that output directory has write permissions
4. Verify input image files exist and are readable

Getting Help

If you encounter issues not covered here:

1. Check the AWS Bedrock documentation
2. Review the Model Context Protocol specification
3. Open an issue on the GitHub repository
4. Check AWS service health dashboard for outages

Development

Running Tests

# Install dependencies
uv sync --dev

# Run all tests
pytest

# Run with coverage
pytest --cov=awslabs --cov-report=html

# Run specific test file
pytest tests/test_server.py

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Type check
pyright

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING for guidelines.