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

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

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