Image Generation MCP Server
A FastMCP server for generating and editing images using OpenAI's gpt-image-1 and Azure FLUX.1-Kontext-pro models. This component is part of the AppKit platform and is designed to be integrated into the main application.
Features
- Text-to-Image Generation: Create images from natural language prompts using multiple AI models
- Image Editing & Inpainting: Edit existing images with text prompts and optional masks (gpt-image-1)
- Multiple Formats: Output as PNG, JPEG, or WEBP with customizable quality
- Prompt Enhancement: Auto-refine prompts via LLM for better results
Configuration
This component uses AppKit's configuration system (appkit_commons) and is configured via MCPImageGeneratorConfig. The settings are loaded from configuration/config.yaml or environment variables mapped by appkit_commons.
Settings
| Setting | Description | Default |
|---|---|---|
backend_server |
URL of the backend server (for retrieving images) | http://localhost:8000 |
max_file_size_mb |
Maximum allowed file size for input images | 10 |
max_images_to_keep |
Storage retention limit for generated images | 50 |
generator |
Active image generator backend (azure or google) |
azure |
azure_api_key |
Azure OpenAI API key | None |
azure_base_url |
Azure OpenAI endpoint URL | None |
azure_prompt_optimizer |
LLM model used for prompt enhancement (Azure) | gpt-5-mini |
azure_image_model |
Image generation model identifier (Azure) | FLUX.1-Kontext-pro |
google_api_key |
Google AI API key | None |
google_prompt_optimizer |
LLM model used for prompt enhancement (Google) | gemini-2.0-flash-001 |
google_image_model |
Image generation model identifier (Google) | imagen-4.0-generate-preview-06-06 |
auth_tokens |
List of MCP tokens and scopes for authentication | [] |
Integration
This module is designed to be integrated into the main AppKit application rather than running standalone. The create_image_mcp_server function returns a configured FastMCP instance which is mounted by the main application.
Usage in AppKit
In app/app.py, the server is initialized effectively as follows:
from appkit_commons.registry import service_registry
from appkit_user.authentication.services import get_verifier
from appkit_mcp_image.server import create_image_mcp_server, init_generators
from appkit_mcp_image.configuration import MCPImageGeneratorConfig
# ... inside initialization ...
image_mcp_config = service_registry().get(MCPImageGeneratorConfig)
_generators = init_generators(image_mcp_config)
# Create and mount the MCP server
servers["/image"] = create_image_mcp_server(
_generators[image_mcp_config.generator],
auth=get_verifier(),
)
Tools & API
generate_image
Create images from text descriptions.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
prompt |
string | required | Image description (max 32,000 chars) |
size |
string | 1024x1024 |
Dimensions: 1024x1024, 1536x1024, 1024x1536, or auto |
output_format |
string | jpeg |
Output format: png, jpeg, or webp |
seed |
integer | 0 |
Random seed for reproducibility (0 = random) |
enhance_prompt |
boolean | true |
Auto-enhance prompt via LLM |
background |
string | auto |
Background: transparent, opaque, or auto |
Example:
generate_image(
prompt="A serene mountain landscape at sunset with golden light reflecting off a lake",
size="1536x1024",
output_format="png",
enhance_prompt=True,
)
edit_image
Edit existing images with text prompts and optional masks for inpainting.
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
prompt |
string | required | Description of desired edits (max 32,000 chars) |
image_paths |
array | required | Image URLs, file paths, or base64 data URLs (max 16) |
mask_path |
string | optional | Optional mask image for inpainting (transparent areas indicate edit zones) |
size |
string | auto |
Output dimensions |
output_format |
string | jpeg |
Output format: png, jpeg, or webp |
background |
string | auto |
Background setting |
Example:
edit_image(
prompt="Add a vibrant rainbow across the sky",
image_paths=["https://example.com/landscape.jpg"],
mask_path="https://example.com/sky_mask.png",
output_format="png",
)
Image Input Formats
Supported input methods for image_paths parameter:
- HTTP/HTTPS URLs:
https://example.com/image.jpg - Local file paths:
/path/to/image.png - Base64 data URLs:
data:image/png;base64,iVBORw0KG...
Inpainting with Masks
For precise control over edits, use mask images:
- Create a PNG image with alpha transparency
- Transparent areas (alpha=0) mark regions to edit
- Opaque areas remain unchanged
- Mask dimensions must match the input image
License
This project is licensed under the MIT License - see LICENSE.md for details.
1 maintainer
Metadata
1 maintainer
Release files for appkit-mcp-image 1.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| appkit_mcp_image-1.16.0.tar.gz | 20.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| appkit_mcp_image-1.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 37.2 kB
Release files / appkit_mcp_image-1.16.0.tar.gz
| Download URL | appkit_mcp_image-1.16.0.tar.gz |
|---|---|
| Size | 20.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
03a00e66ff6346bf3741e3aa1ca554f077676fff8532f0ffedc37103698c5a5c
|
|
BLAKE2b-256 checksum How to use checksums |
9df3ae365c56bdbba8d9b3fc82e5faa3bedbf1f47daff2549a1c49c4dfed2d97
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / appkit_mcp_image-1.16.0-py3-none-any.whl
| Download URL | appkit_mcp_image-1.16.0-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f82fe9f1cd57fcf6785de07d77a60837cfcccb52d509cee0d60e883ed108593
|
|
BLAKE2b-256 checksum How to use checksums |
ec765bdc67953fe956afe3970c0e823c36e54603df0b552a3c9efd091e9e8b5c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
