Azure Image Editor MCP Server
中文 | English
This is an MCP (Model Context Protocol) server that supports Azure AI Foundry image generation and editing capabilities.
Features
- Text-to-Image Generation - Generate high-quality images from text descriptions using Azure AI Foundry models
- Image Editing - Edit and modify existing images
- Configurable Models - Support for multiple Azure AI models via environment variables
Demo
Click 👇 to go to the demo on YouTube
Project Structure
azure-image-editor/
├── .venv/ # Python virtual environment
├── src/
│ ├── azure_image_client.py # Azure API client
│ ├── mcp_server.py # STDIO MCP server
│ └── mcp_server_http.py # HTTP/JSON-RPC MCP server
├── tests/ # Test files
├── logs/ # Server logs
├── tmp/ # Temporary files
├── requirements.txt # Python dependencies
├── .env # Environment configuration
├── .env.example # Environment configuration template
└── README.md # Project documentation
Prerequisites
⚠️ Important: Before using this MCP server, you must deploy the required model in your Azure AI Foundry environment.
Azure AI Foundry Model Deployment
- Access Azure AI Foundry: Go to Azure AI Foundry
- Deploy the model: Deploy
flux.1-kontext-pro(or your preferred model) in your Azure AI Foundry workspace - Get deployment details: Note down your:
- Base URL (endpoint)
- API key
- Deployment name
- Model name
Without proper model deployment, the MCP server will not function correctly.
Installation and Setup
- Clone and setup environment:
git clone https://github.com/satomic/Azure-AI-Image-Editor-MCP.git
cd azure-image-editor
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# or .venv\Scripts\activate # Windows
pip install -r requirements.txt
Server Modes
This project supports two MCP server modes:
1. STDIO Mode (Default)
Communicates via standard input/output. Suitable for VSCode integration.
2. HTTP/JSON-RPC Mode
Communicates via HTTP with JSON-RPC 2.0 protocol. Suitable for web applications and remote access.
Configuration
Configure STDIO Mode (VSCode MCP)
Add the following to your VSCode MCP configuration:
{
"servers": {
"azure-image-editor": {
"command": "/full/path/to/.venv/bin/python",
"args": ["/full/path/to/azure-image-editor/src/mcp_server.py"],
"env": {
"AZURE_BASE_URL": "https://your-endpoint.services.ai.azure.com", // deployment endpoint
"AZURE_API_KEY": "${input:azure-api-key}",
"AZURE_DEPLOYMENT_NAME": "FLUX.1-Kontext-pro", // The name you gave your deployment
"AZURE_MODEL": "flux.1-kontext-pro", // Default model
"AZURE_API_VERSION": "2025-04-01-preview" // Default API version
}
}
},
"inputs": [
{
"id": "azure-api-key",
"type": "promptString",
"description": "Enter your Azure API Key",
"password": "true"
}
]
}
Important: Replace /full/path/to/ with the actual absolute path to this project directory.
Configure HTTP/JSON-RPC Mode
Option 1: Run directly with environment variables
# Activate virtual environment
source .venv/bin/activate # Linux/Mac
# or .venv\Scripts\activate # Windows
# Set environment variables
export AZURE_BASE_URL="https://your-endpoint.services.ai.azure.com"
export AZURE_API_KEY="your-api-key"
export AZURE_DEPLOYMENT_NAME="FLUX.1-Kontext-pro"
export AZURE_MODEL="flux.1-kontext-pro"
export AZURE_API_VERSION="2025-04-01-preview"
# Optional: Configure server host and port (defaults to 127.0.0.1:8000)
export MCP_SERVER_HOST="0.0.0.0" # Listen on all interfaces
export MCP_SERVER_PORT="8000" # Server port
# Start the HTTP server
python src/mcp_server_http.py
Option 2: Use .env file
Create a .env file in the project root:
AZURE_BASE_URL=https://your-endpoint.services.ai.azure.com
AZURE_API_KEY=your-api-key
AZURE_DEPLOYMENT_NAME=FLUX.1-Kontext-pro
AZURE_MODEL=flux.1-kontext-pro
AZURE_API_VERSION=2025-04-01-preview
# Optional server configuration
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000
DEFAULT_IMAGE_SIZE=1024x1024
Then start the server:
source .venv/bin/activate
python src/mcp_server_http.py
Server Endpoints
When the HTTP server is running, the following endpoints are available:
- JSON-RPC Endpoint:
http://127.0.0.1:8000/- Main JSON-RPC 2.0 endpoint (POST) - Health Check:
http://127.0.0.1:8000/health- Server health status (GET)
Connecting to HTTP Server
Important for HTTP Mode: When using HTTP mode, even if you provide an output_path parameter, the server will:
- Save the image to the specified path on the server
- Also return the base64-encoded image data to the client
This allows the MCP client to receive the image data and save it locally without needing additional file transfer.
Using VSCode MCP Client:
{
"servers": {
"azure-image-editor-http": {
"type": "http",
"url": "http://127.0.0.1:8000"
}
}
}
Using curl:
# List available tools
curl -X POST http://127.0.0.1:8000/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
# Call generate_image tool
curl -X POST http://127.0.0.1:8000/ \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024",
"output_path": "./images/sunset.png"
}
}
}'
Available MCP Tools
1. generate_image
Generate images from text prompts
Parameters:
prompt(required): English text description for image generationsize(optional): Image size - "1024x1024", "1792x1024", "1024x1792", default: "1024x1024"output_path(optional): Output file path, returns base64 encoded image if not provided
Example:
{
"name": "generate_image",
"arguments": {
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024",
"output_path": "/path/to/output/image.png"
}
}
2. edit_image
Edit existing images with intelligent dimension preservation
Parameters:
STDIO mode:
image_path(required): Path to the image file to editprompt(required): English text description of how to edit the imagesize(optional): Output image size, uses original dimensions if not specifiedoutput_path(optional): Output file path
HTTP mode:
image_data_base64(required): Base64 encoded image data- Supports raw base64 format:
iVBORw0KGgoAAAANS... - Supports Data URL format:
data:image/png;base64,iVBORw0KGgoAAAANS...
- Supports raw base64 format:
prompt(required): English text description of how to edit the imagesize(optional): Output image size, uses original dimensions if not specifiedoutput_path(optional): Output file path (server-side), image data always returned to client
Example (STDIO mode):
{
"name": "edit_image",
"arguments": {
"image_path": "/path/to/input/image.png",
"prompt": "Make this black and white",
"output_path": "/path/to/output/edited_image.png"
}
}
Example (HTTP mode):
{
"name": "edit_image",
"arguments": {
"image_data_base64": "iVBORw0KGgoAAAANS...",
"prompt": "Make this black and white",
"output_path": "/tmp/edited_image.png"
}
}
Or using Data URL format:
{
"name": "edit_image",
"arguments": {
"image_data_base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
"prompt": "Make this black and white",
"output_path": "/tmp/edited_image.png"
}
}
Technical Specifications
-
Python version: 3.8+
-
Main dependencies:
mcp: MCP protocol supporthttpx: HTTP client with timeout handlingpillow: Image processing and dimension detectionaiofiles: Async file operationspydantic: Data validationpython-dotenv: Environment variable managementstarlette: ASGI framework for HTTP server (HTTP mode only)uvicorn: ASGI server (HTTP mode only)
-
Azure AI Foundry:
- Default model: flux.1-kontext-pro (configurable)
- Default API version: 2025-04-01-preview (configurable)
- Supported image sizes: 1024x1024, 1792x1024, 1024x1792
- Timeout: 5 minutes per request
Troubleshooting
- Timeout Errors: Image processing has 5-minute timeout, check network connectivity
- API Errors: Verify Azure credentials and endpoint URL
- Dependency Issues: Ensure virtual environment is activated and dependencies installed
- Server Connection Issues: Verify VSCode MCP configuration path is correct
License
MIT License