Image Proxy MCP Server

Local MCP server (stdio transport) that proxies image generation to Azure endpoints, saves results to disk, and returns only file paths to Claude Desktop. This eliminates the base64 context window overflow problem entirely.

The Problem

When Claude Desktop calls image generation through the remote multimodel MCP, the response includes base64-encoded image data (1-4MB of text per image). This consumes 30-60% of the available context window and frequently causes failures.

The Solution

This local MCP server:

1. Receives the image generation request from Claude Desktop
2. Calls the Azure endpoint directly via HTTP
3. Receives the base64 response server-side (never enters the context)
4. Saves the image to a local directory
5. Returns only a compact JSON with the file path (~200 bytes vs ~2MB)

Setup

1. Install Dependencies

cd tools/image-proxy
npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your Azure endpoints (keys are optional)

Authentication — two modes, per endpoint:

| Mode | Setup | When to use | |------|-------|-------------| | Managed Identity (recommended) | Set endpoints only, leave keys blank. Run az login locally. | Zero secrets, same as main MCP server | | API Key | Set both endpoint + key env vars | Quick testing, no az login needed |

If a key is set, it takes priority. If blank, the server uses DefaultAzureCredential (az login locally, system-assigned MI on Azure).

You need endpoints for:

• Azure OpenAI (for gpt-image-1.5, dall-e-3) — cognitiveservices.azure.com
• Azure AI Services (for flux-kontext-pro) — services.ai.azure.com

Both are in your Azure AI Foundry portal under each deployment.

3. Test

node test.js

4. Add to Claude Desktop

Add the image-proxy entry to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "image-proxy": {
      "command": "node",
      "args": ["/absolute/path/to/tools/image-proxy/index.js"],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com",
        "AZURE_AI_SERVICES_ENDPOINT": "https://your-resource.services.ai.azure.com",
        "IMAGE_OUTPUT_DIR": "~/Documents/generated-images"
      }
    }
  }
}

With managed identity, only endpoints are needed — no keys. Run az login and the server authenticates automatically. To use API keys instead, add AZURE_OPENAI_API_KEY and/or AZURE_AI_SERVICES_KEY to the env block.

Tools

| Tool | Description | |------|-------------| | generate_image | Generate an image and save to disk. Returns only the file path. Models: gpt-image-1.5, dall-e-3, flux-kontext-pro | | base64_to_file | Convert a base64 string already in context to a file on disk | | list_generated_images | List all previously generated images with metadata | | cleanup_images | Remove old generated images (dry_run=true by default) |

Architecture

Claude Desktop
    |
    |-- (stdio) --> image-proxy MCP (LOCAL)
    |                   |
    |                   |-- (HTTPS) --> Azure OpenAI (gpt-image-1.5, dall-e-3)
    |                   |-- (HTTPS) --> Azure AI Services (flux-kontext-pro)
    |                   |
    |                   v
    |               ~/Documents/generated-images/
    |                   |
    |                   v
    |               Returns: { filePath, model, size } (~200 bytes)
    |
    |-- (HTTP)  --> multimodel MCP (Azure, for non-image tasks)

Context Window Savings

| Scenario | Without Proxy | With Proxy | |----------|--------------|------------| | 1 image (1024x1024) | ~2-4 MB base64 in context | ~200 bytes path | | 3 images in conversation | Context overflow / failure | ~600 bytes | | Image + follow-up edits | Cascading failures | Works normally |