AI Image Generation Server with MCP Interface

# 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](https://block.github.io/goose/docs/tutorials/custom-extensions/). ## Setup 1. Create a virtual environment, use `.venv` mandatorily: ```bash virtualenv .venv ``` 2. Activate the virtual environment: ```bash source .venv/bin/activate ``` 3. Install the MCP package (for Goose integration): ```bash 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:** ```bash 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 ```bash 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 ```bash 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: - Explore available tools and their documentation - Test the `generate_image` tool with your own prompts - View request/response history - Debug any issues with the MCP server **Custom port for image generation service:** ```bash 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: ```bash 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: ```json { "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](https://ollama.com/library/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) - Handles the actual image generation using Stable Diffusion - Provides a simple HTTP API for image generation - Returns image URL, dimensions, and metadata - Includes a direct endpoint to serve the generated images - Runs on port 5000 by default (customizable with --port) - Runs in a separate thread within the same process as the MCP server 2. **MCP Server** (src/image_gen_mcp/server.py) - Provides a standardized MCP interface for AI agents - Forwards requests to the integrated Image Generation Service - Returns a properly formatted MCP image object with URL and metadata ## Stopping the Service Use Ctrl+C to stop both services, as they now run within the same process.