GPT Image MCP

FastAPI + FastMCP service for generating and editing images with OpenAI image models.

What you get

• MCP tools: generate_image, edit_image, health
• Streamable HTTP MCP transport at POST /mcp/
• HTTP health check at GET /health
• Static image hosting at GET /images/{filename}
• Optional bearer auth for MCP and image routes
• Upload validation, retry logic, structured logs, and image cleanup

MCP tools

• generate_image creates a new image from text.
• edit_image edits one or more images and supports an optional mask.
• health returns a simple service status payload.

Environment variables

Copy the example file first:

cp .env.example .env

Required:

• OPENAI_API_KEY - OpenAI API key

Optional:

• PUBLIC_URL - public base URL for returned image links
• MCP_API_KEY - bearer token required for /mcp/ and /images/*
• IMAGE_DIR - image storage directory
• LOG_LEVEL - logging level, default INFO
• MAX_UPLOAD_MB - max size for uploaded images, default 50
• MAX_MASK_MB - max size for masks, default 4
• MAX_IMAGE_EDGE_PX - max image edge length, default 8192
• IMAGE_RETENTION_DAYS - cleanup retention window, default 7
• CLEANUP_INTERVAL_SECONDS - cleanup interval, default 86400
• OPENAI_RETRY_ATTEMPTS - retry count for OpenAI image calls, default 3
• OPENAI_RETRY_BASE_DELAY_SECONDS - retry backoff base, default 0.75
• REQUEST_TIMEOUT_SECONDS - timeout for remote image downloads, default 60

Run locally

pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8080

The MCP endpoint is available at:

• http://localhost:8080/mcp/

Run with Docker

docker compose up --build

Tests

python3 -m unittest discover -s tests -p "test*.py" -v

If you have pytest installed:

pytest -q

Verify on GitHub

git remote -v
git push -u origin main

If you have not connected the repository yet:

git branch -M main
git remote add origin git@github.com:<your-username>/<your-repo>.git
git push -u origin main

Notes

• POST /mcp/ is the MCP transport endpoint expected by LobeHub.
• generate_image and edit_image return the same response shape.
• edit_image accepts image files stored under IMAGE_DIR or public http(s) URLs.
• Local paths outside IMAGE_DIR and private or localhost remote URLs are rejected for security.
• Returned image URLs use PUBLIC_URL when it is set, otherwise they fall back to /images/{filename}.
• Old images are cleaned up automatically according to IMAGE_RETENTION_DAYS.

Troubleshooting

• 401 Unauthorized
  • Set MCP_API_KEY on the server and send Authorization: Bearer <token> from the client.
  • If you are using LobeHub or nginx, make sure the proxy forwards the Authorization header.
• 404 Not Found on /mcp/
  • Use the trailing slash: POST /mcp/.
  • Confirm nginx proxies to the local container port and does not rewrite the path.
  • Verify the FastMCP server is mounted through app.main:app.
• Invalid image or Unsupported image
  • Use a real PNG, JPEG, or WEBP input image.
  • For masks, use PNG only and keep the mask the same size as the first input image.
  • Check that the file is not corrupted and is smaller than MAX_UPLOAD_MB or MAX_MASK_MB.
• File not found or Remote image host errors
  • Keep local file references under IMAGE_DIR.
  • Use public, reachable http(s) URLs only.
• OpenAI API errors
  • Confirm OPENAI_API_KEY is set and valid.
  • Check rate limits, quota, and model availability.
  • Verify the server has outbound network access to OpenAI.
• Image URL is not reachable
  • Set PUBLIC_URL to the external domain that serves the service.
  • Make sure nginx serves /images/ correctly and the image directory is mounted into the container.