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

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.

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).

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