mcp-server-bedrock-image

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)

Quickstart

Prerequisites

• Python 3.12+
• AWS account with Bedrock access to Stability AI models
• uv package manager

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

<details> <summary><strong>Claude Code</strong></summary>

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.

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json:

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

</details>

<details> <summary><strong>VS Code</strong></summary>

Add to .vscode/mcp.json:

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

</details>

<details> <summary><strong>Windsurf</strong></summary>

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

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

</details>

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