ImageGenMcp.Server
1.0.0
See the version list below for details.
dotnet tool install --global ImageGenMcp.Server --version 1.0.0
dotnet new tool-manifest
dotnet tool install --local ImageGenMcp.Server --version 1.0.0
#tool dotnet:?package=ImageGenMcp.Server&version=1.0.0
nuke :add-package ImageGenMcp.Server --version 1.0.0
ImageGen MCP Server
A .NET/C# Model Context Protocol (MCP) server over stdio for creating and editing images through Azure AI Foundry / Azure OpenAI. It defaults to OpenAI's newer gpt-image-2 model name and returns actual MCP image content blocks (image/png or image/jpeg) instead of plain URLs.
What is included
generate_imageMCP tool for image creation.edit_imageMCP tool for image editing with an input image, optional mask, and optional extra reference images.- Azure Foundry v1 image endpoint support:
/openai/v1/images/{generations|edits}?api-version=preview. - Azure deployment endpoint compatibility:
/openai/deployments/{deployment}/images/{generations|edits}?api-version=.... - API key auth and Microsoft Entra ID auth with configurable token scope.
- MCP image returns via
ImageContentBlock.FromBytes(...), so clients receive properly base64-encoded image payloads. - Tests around request construction, response decoding, validation, and MCP content block creation.
Package baseline
The project was scaffolded with current NuGet packages resolved during setup:
| Package | Version | Purpose |
|---|---|---|
ModelContextProtocol |
1.2.0 |
Official C# MCP SDK, stdio transport, tool attributes, image content blocks |
Microsoft.Extensions.Hosting |
10.0.7 |
Generic host for the stdio server |
Microsoft.Extensions.Http |
10.0.7 |
Typed HttpClient for Azure Foundry calls |
Microsoft.Extensions.Options.ConfigurationExtensions |
10.0.7 |
Configuration binding |
Microsoft.Extensions.Configuration.UserSecrets |
10.0.7 |
Local secret support |
Microsoft.Extensions.Logging.Console |
10.0.7 |
Logging to stderr for MCP stdio safety |
Azure.Identity |
1.21.0 |
Optional Entra ID auth with DefaultAzureCredential |
Note: The OpenAI/Azure .NET SDKs expose image functionality, but the newest image model surfaces can lag in strongly typed SDK options. This server calls the Azure Foundry image REST endpoints directly and exposes only image-generation/editing controls that are useful to an MCP client.
Configuration
The server reads configuration from appsettings.json, environment variables, user-secrets, and a local .env file. A placeholder .env was created for local development and is ignored by git.
Required API key setup:
AzureFoundry__Endpoint=https://YOUR-RESOURCE-NAME.openai.azure.com/
AzureFoundry__ApiKey=YOUR_AZURE_OPENAI_API_KEY
AzureFoundry__Model=gpt-image-2
AzureFoundry__ApiVersion=preview
AzureFoundry__EndpointMode=V1Images
AzureFoundry__Authentication=ApiKey
For Entra ID / managed identity:
AzureFoundry__Endpoint=https://YOUR-RESOURCE-NAME.openai.azure.com/
AzureFoundry__Model=gpt-image-2
AzureFoundry__ApiVersion=preview
AzureFoundry__EndpointMode=V1Images
AzureFoundry__Authentication=EntraId
AzureFoundry__TokenScope=https://ai.azure.com/.default
If your Azure resource requires the classic Azure OpenAI audience instead, set:
AzureFoundry__TokenScope=https://cognitiveservices.azure.com/.default
Endpoint modes
| Mode | URL shape | When to use |
|---|---|---|
V1Images |
/openai/v1/images/generations?api-version=preview with model in body |
Preferred Azure Foundry/OpenAI-compatible v1 flow |
DeploymentImages |
/openai/deployments/{deployment}/images/generations?api-version=2025-04-01-preview |
Older Azure OpenAI deployment-name flow |
Safety limits
| Setting | Default | Purpose |
|---|---|---|
MaxPromptCharacters |
32000 |
Bounds prompt size |
MaxImagesPerRequest |
10 |
Bounds n |
MaxInputImageBytes |
52428800 |
Bounds base64 edit inputs |
MaxOutputImageBytes |
52428800 |
Bounds HTTPS URL responses before converting them to MCP image content |
TimeoutSeconds |
300 |
Bounds Azure Foundry calls |
MCP client registration
Example stdio registration:
{
"mcpServers": {
"image-gen": {
"command": "dotnet",
"args": [
"run",
"--project",
"D:\\git\\image-gen-mcp\\src\\ImageGenMcp.Server\\ImageGenMcp.Server.csproj"
]
}
}
}
For package-based usage with .NET SDK 10 or later, publish the tool package to NuGet.org or a private NuGet feed and run it with dnx:
{
"mcpServers": {
"image-gen": {
"command": "dotnet",
"args": [
"dnx",
"ImageGenMcp.Server"
]
}
}
}
If the package is on a private feed, add the feed either through nuget.config or as part of the command arguments:
{
"mcpServers": {
"image-gen": {
"command": "dotnet",
"args": [
"dnx",
"ImageGenMcp.Server",
"--add-source",
"https://YOUR-FEED-URL/index.json"
]
}
}
}
For pinned deployments, include the package version in the package reference, for example ImageGenMcp.Server@1.0.0. dnx downloads and runs the tool without permanently installing it.
The packaged tool command name is image-gen-mcp, which is used when installing the package as a global or local .NET tool.
Tools
generate_image
Use when a user wants a new image created from a text description. The tool returns image content directly.
Key parameters:
| Parameter | Default | Notes |
|---|---|---|
prompt |
required | Describe subject, setting, style, composition, lighting, colors, mood, camera/framing, text, and constraints. |
size |
auto |
Use auto unless exact dimensions/aspect ratio matter. Custom dimensions use WIDTHxHEIGHT; both edges must be multiples of 16, long edge ⇐ 3840px, aspect ratio ⇐ 3:1, and total pixels between 655,360 and 8,294,400. |
quality |
high |
low for drafts, medium for balanced results, high for final/high-detail images. |
n |
1 |
Number of alternatives. Use 1 unless the user asks for multiple options. |
outputFormat |
png |
png for crisp graphics/text/UI/lossless output; jpeg for photos or smaller files. |
outputCompression |
unset | JPEG compression 0-100; use only with jpeg. Higher values are smaller/more compressed. |
Example:
{
"prompt": "A cinematic macro photograph of a crystal fox in a snowy pine forest, volumetric dawn light",
"size": "3840x2160",
"quality": "high",
"outputFormat": "jpeg",
"outputCompression": 90
}
edit_image
Use when a user provides an image and wants it changed, restyled, repaired, expanded, or combined with reference images. The tool returns image content directly.
Key edit-only parameters:
| Parameter | Default | Notes |
|---|---|---|
prompt |
required | Describe what should change, what must remain unchanged, and any style/composition requirements. |
imageBase64 |
required | Input image to edit as base64 bytes or a data URL. |
imageMimeType |
image/png |
Input file type when imageBase64 is not a data URL. Usually image/png, image/jpeg, or image/webp. |
maskBase64 |
unset | Optional mask image. Use only when the edit should be limited to specific areas. |
maskMimeType |
image/png |
Mask image file type. Usually image/png. |
additionalImagesBase64 |
unset | Extra reference images when the edit should borrow style, identity, objects, or composition from other images. |
size |
auto |
Use auto unless exact output dimensions/aspect ratio matter. Custom dimensions follow the same rules as generation. |
quality |
high |
low for drafts, medium for balanced results, high for final/high-detail edits. |
n |
1 |
Number of edited alternatives. Use 1 unless the user asks for multiple options. |
outputFormat |
png |
png for crisp graphics/text/UI/lossless output; jpeg for photos or smaller files. |
outputCompression |
unset | JPEG compression 0-100; use only with jpeg. Higher values are smaller/more compressed. |
inputFidelity |
unset | Use high for identity/product/style preservation; use low for freer transformations. |
Current gpt-image-2 coverage
Implemented as AI-facing first-class parameters: prompt, arbitrary custom size validation, quality, n, output format, output compression, edit image(s), mask, and input fidelity.
Deliberately not exposed as MCP tool parameters: model/deployment, user, response_format, raw stream, partial_images, background, and arbitrary JSON pass-through. Those are configuration, telemetry, transport, unsupported, or API escape-hatch details rather than reliable MCP image-creation controls. The server config chooses the model/deployment and the tool always returns MCP image blocks.
partial_images is not exposed because MCP tool calls return a final tool result, not incremental image-generation events. background is not exposed because gpt-image-2 does not currently support transparent backgrounds, and sending background controls creates confusing failure modes.
Development
Restore/build/test:
dotnet restore
dotnet build
dotnet test
Run locally as an MCP stdio server:
dotnet run --project src/ImageGenMcp.Server/ImageGenMcp.Server.csproj
The process waits for MCP JSON-RPC on stdin. Logs are written to stderr so stdout stays protocol-clean.
Package as a .NET tool:
dotnet pack src/ImageGenMcp.Server/ImageGenMcp.Server.csproj
The package is written to artifacts/packages/. To test the package locally with dnx, use that directory as an additional package source.
Security and operational notes
- Do not commit real
.envvalues. Use user-secrets, environment variables, managed identity, or a vault-backed deployment. - Prompt, input image, and URL-fetched output image sizes are bounded to reduce accidental runaway cost and resource usage.
- The server does not log prompts, image bytes, masks, or API keys.
- URL image responses are fetched only over HTTPS before being returned as MCP image blocks.
- NuGet audit is enabled in the server project for moderate-or-higher vulnerabilities across direct and transitive dependencies.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.