Azure OpenAI Image 1.5 MCP Server

A C# MCP server that provides text-to-image generation and image editing/inpainting capabilities via Azure OpenAI's Image 1.5 (gpt-image-1.5) model.

Features

• 2 MCP tools: generate_image and edit_image
• Dual transport: stdio (default) and HTTP
• Dual auth: API Key and Azure Identity (DefaultAzureCredential)
• Returns images as MCP ImageContentBlock for inline display (Image 1.5 always returns base64)
• Full Image 1.5 API coverage: background transparency, output compression, moderation level
• Built with .NET 10 and the official MCP C# SDK

Project Layout

mcp-oai-image/
├── mcp-oai-image.sln
├── README.md
├── src/mcp-oai-image/
└── tests/
    ├── mcp-oai-image.Tests/
    └── mcp-oai-image.IntegrationTests/

Prerequisites

• .NET 10 SDK
• Azure OpenAI resource with an Image 1.5 (gpt-image-1) model deployed
• API Key or Azure Identity credentials

[!NOTE] When using Azure Identity, the server authenticates with DefaultAzureCredential. Make sure your environment can acquire a token, for example via az login, Visual Studio, VS Code, managed identity, or environment-based credentials.

Installation

Install as a .NET global tool:

dotnet tool install -g mcp-oai-image

Update to the latest version:

dotnet tool update -g mcp-oai-image

Quick Start

Run with the default stdio transport:

mcp-oai-image

Run with HTTP transport:

mcp-oai-image --transport http

The HTTP server listens on http://localhost:3001 by default.

Building from source

cd src/mcp-oai-image
dotnet build
dotnet run

Configuration

Environment Variables

Variable	Required	Description
AZURE_OPENAI_ENDPOINT	Yes	Azure OpenAI resource endpoint URL
AZURE_OPENAI_API_KEY	Yes (if using API Key auth)	Azure OpenAI API key
AZURE_OPENAI_DEPLOYMENT_NAME	Yes	Deployment name for Image 1.5 model
AZURE_OPENAI_API_VERSION	No	API version (default: 2025-04-01-preview)
MCP_TRANSPORT	No	Transport type: stdio (default) or http

For Azure Identity authentication, set AzureOpenAI:AuthMethod to AzureIdentity in configuration. If you prefer environment variables for that setting, use the standard .NET hierarchical key format:

# Windows PowerShell
$env:AzureOpenAI__AuthMethod = "AzureIdentity"

# bash/zsh
export AzureOpenAI__AuthMethod=AzureIdentity

appsettings.json

The application includes the following configuration structure:

{
  "AzureOpenAI": {
    "Endpoint": "https://<your-resource>.openai.azure.com/",
    "ApiKey": "<your-api-key>",
    "DeploymentName": "<your-deployment>",
    "ApiVersion": "2025-04-01-preview",
    "AuthMethod": "ApiKey"
  },
  "McpTransport": "stdio",
  "HttpPort": 3001,
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Configuration notes:

• AuthMethod supports ApiKey and AzureIdentity.
• HttpPort controls the HTTP listener port when the server is started in HTTP mode.
• Transport is resolved from the --transport command-line argument first, then MCP_TRANSPORT.
• Environment variables override the Azure OpenAI connection settings shown above.

MCP Client Configuration

VS Code (stdio)

// .vscode/mcp.json
{
  "servers": {
    "aoai-image": {
      "type": "stdio",
      "command": "mcp-oai-image",
      "env": {
        "AZURE_OPENAI_ENDPOINT": "<your-endpoint>",
        "AZURE_OPENAI_API_KEY": "<your-key>",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "<your-deployment>"
      }
    }
  }
}

VS Code (HTTP)

// .vscode/mcp.json
{
  "servers": {
    "aoai-image": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

Start the server first:

mcp-oai-image --transport http

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "aoai-image": {
      "command": "mcp-oai-image",
      "env": {
        "AZURE_OPENAI_ENDPOINT": "<your-endpoint>",
        "AZURE_OPENAI_API_KEY": "<your-key>",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "<your-deployment>"
      }
    }
  }
}

GitHub Copilot CLI

First, install the tool if you haven't already:

dotnet tool install -g mcp-oai-image

Then add the server to ~/.copilot/mcp-config.json, or use the /mcp add slash command from an interactive Copilot CLI session.

API Key auth:

// ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "aoai-image": {
      "type": "stdio",
      "command": "mcp-oai-image",
      "tools": ["*"],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "<your-endpoint>",
        "AZURE_OPENAI_API_KEY": "<your-key>",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "<your-deployment>"
      }
    }
  }
}

Azure Identity auth:

// ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "aoai-image": {
      "type": "stdio",
      "command": "mcp-oai-image",
      "tools": ["*"],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "<your-endpoint>",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "<your-deployment>",
        "AzureOpenAI__AuthMethod": "AzureIdentity"
      }
    }
  }
}

[!TIP] Make sure you're logged in via az login before starting the server so DefaultAzureCredential can acquire a token.

Available Tools

generate_image

Generates one or more images from a text prompt using Azure OpenAI Image 1.5.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image
size	string	No	1024x1024, 1024x1536, 1536x1024, auto
quality	string	No	low, medium, high, auto
outputFileFormat	string	No	png, jpeg, webp (default png)
outputCompression	int	No	Compression level 0-100 for jpeg/webp (ignored for png)
background	string	No	transparent, opaque, auto
moderation	string	No	auto, low
n	int	No	Number of images, 1-10 (default 1)
outputPath	string	No	Directory path to save generated images. Files auto-named image_1.png, image_2.png, etc. Directory created if needed

Behavior notes:

• Image 1.5 always returns base64-encoded image data — images are returned as inline ImageContentBlock.
• If Azure OpenAI returns a revised prompt, it is included as a text block.
• When outputPath is provided, images are saved to disk and the file path is included in the response alongside the inline image.

edit_image

Edits an existing image using a prompt, with optional mask-based inpainting. Supports multiple input images for reference-based editing (e.g., combining a photo with a logo).

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the desired edit
imagePath	string	Yes	Absolute path to the primary source image
maskPath	string	No	Absolute path to the optional mask image
additionalImagePaths	string	No	JSON array of absolute paths to additional reference images, e.g. ["C:\\logo.png"]
size	string	No	1024x1024, 1024x1536, 1536x1024, auto
quality	string	No	low, medium, high, auto
inputFidelity	string	No	low, high
outputFileFormat	string	No	png, jpeg, webp (default png)
outputCompression	int	No	Compression level 0-100 for jpeg/webp (ignored for png)
background	string	No	transparent, opaque, auto
outputPath	string	No	Directory path to save the edited image. Files auto-named image_1.png, etc. Directory created if needed

Behavior notes:

• imagePath must point to an existing local file.
• maskPath is optional; when provided, it must point to an existing local file. White areas of the mask are edited; black areas are preserved. The mask is applied to the primary image.
• additionalImagePaths enables multi-image editing — for example, providing a photo and a logo to stamp the logo onto the photo. All paths must point to existing files.
• When using inputFidelity: "high", input image details are better preserved. The first image gets the highest fidelity.
• When outputPath is provided, the edited image is saved to disk and the file path is included in the response.

Example Prompts

• "Generate a watercolor painting of a mountain sunset"
• "Generate 3 variations of a minimalist logo for a coffee shop with a transparent background"
• "Generate a logo and save it to C:\images" (with outputPath)
• "Edit this image to add a rainbow in the sky" (with imagePath)
• "Stamp this logo onto the woman's shirt" (with imagePath + additionalImagePaths containing the logo)

Running Tests

# Unit tests
dotnet test tests/mcp-oai-image.Tests

# Integration tests (requires Azure credentials)
dotnet test tests/mcp-oai-image.IntegrationTests

License

MIT