AI Image Generation Server with MCP Interface

This project provides a Model Context Protocol (MCP) server with integrated Stable Diffusion image generation capabilities, enabling AI agents to request and receive generated images.

This project is based on the example provided by Block's Goose Custom Extension tutorial.

Setup

1. Create a virtual environment, use `.venv` mandatorily:

virtualenv .venv

2. Activate the virtual environment:

source .venv/bin/activate

3. Install the MCP package (for Goose integration):

pip install -e .

Running the Service

The MCP server includes the integrated image generation service. You can start both with a single command:

Standard mode:

source .venv/bin/activate  # Activate your virtualenv
export IMAGE_GEN_DIR=/absolute/path/to/folder # Set generated images target folder
image-gen-mcp

Development mode with FastMCP Inspector:

Open two terminals:

Terminal 1

source .venv/bin/activate  # Activate your virtualenv
export IMAGE_GEN_DIR=/absolute/path/to/folder # Set generated images target folder
image-gen-mcp # Start image generation service (and a MCP server we won't use)

Terminal 2

source .venv/bin/activate  # Activate your virtualenv
export IMAGE_GEN_DIR=/absolute/path/to/folder # Set generated images target folder
mcp dev src/image_gen_mcp/server.py # Start MCP server with Inspector

Note: Only when using development mode, the image generation service must be started separately.

This will start the MCP server with the FastMCP Inspector, which provides:

1. A web interface at http://127.0.0.1:6274 for testing and debugging

2. A proxy server on port 6277 for forwarding MCP requests

Using the FastMCP Inspector:

1. Open http://127.0.0.1:6274 in your browser

2. Use the interactive interface to:

Custom port for image generation service:

source .venv/bin/activate  # Activate your virtualenv
export IMAGE_GEN_DIR=/absolute/path/to/folder # Set generated images target folder
image-gen-mcp --port 5001

Direct API Access

Generate an image by sending a POST request to the image generation service:

curl -X POST http://localhost:5000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A futuristic cityscape at sunset"}'

The response will include the URL to access the generated image along with metadata:

{
  "type": "image",
  "format": "png",
  "url": "http://localhost:5000/images/123e4567-e89b-12d3-a456-426614174000.png",
  "width": 512,
  "height": 512,
  "filename": "123e4567-e89b-12d3-a456-426614174000.png",
  "filepath": "generated_images/123e4567-e89b-12d3-a456-426614174000.png",
  "mime_type": "image/png",
  "prompt": "A futuristic cityscape at sunset",
  "alt_text": "AI-generated image of: A futuristic cityscape at sunset"
}

You can access the generated image directly via the returned `image_url`.

File Organization

• `src/image_gen_mcp/` - Package directory containing the implementation
  • `server.py` - The MCP server implementation
  • `generator.py` - The image generation service
  • `__init__.py` - Package initialization and CLI entry point
  • `__main__.py` - Enables running the package as a module

Integration with Goose

To add this MCP server as an extension in Goose:

1. Go to `Settings > Extensions > Add`.

2. Set the `Type` to `StandardIO`.

3. Provide ID "image_generator", name "Image Generator", and an appropriate description.

4. In the `Command` field, provide the absolute path to your executable:

uv run /full/path/to/your/project/.venv/bin/image-gen-mcp

5. Add an environment variable `IMAGE_GEN_DIR` and pick a folder where generated images will be stored

Once integrated, you can use the image generation tool in Goose by asking it to generate an image with a specific prompt.

It works immediately when using OpenAI GPT-4o.

It is possible to run everytthing locally with Ollama, After trying a few models, the only one that worked is mistral-small3.1.

Even on a high-end MacBookPro, the response from mistral-small3.1 is much slower than with OpenAI GPT-4o.

Service Architecture

Both services are integrated into a single application:

1. Image Generation Service (src/image_gen_mcp/generator.py)

2. MCP Server (src/image_gen_mcp/server.py)

Stopping the Service

Use Ctrl+C to stop both services, as they now run within the same process.