Imagegen MCP D3

🚀 DALL-E 3 MCP Server

A Model Context Protocol (MCP) server that provides DALL-E 3 image generation capabilities. This server allows LLMs to generate high-quality images using OpenAI's DALL-E 3 model through the standardized MCP interface.

🚀 Quick Start

This MCP server enables LLMs to generate high - quality images with OpenAI's DALL - E 3 model via the MCP interface.

✨ Features

• 🎨 High - Quality Image Generation: Uses DALL - E 3 for state - of - the - art image creation.
• 🔧 Flexible Configuration: Support for different sizes, quality levels, and styles.
• 📁 Automatic File Management: Handles directory creation and file saving.
• 🛡️ Robust Error Handling: Comprehensive error handling with detailed feedback.
• 📊 Detailed Logging: Comprehensive logging for debugging and monitoring.
• 🚀 TypeScript: Fully typed for better development experience.
• 🧪 Well Tested: Comprehensive test suite with high coverage.

📦 Installation

Using NPX (Recommended)

npx imagegen-mcp-d3

Using NPM

npm install -g imagegen-mcp-d3

From Source

git clone https://github.com/chrisurf/imagegen-mcp-d3.git
cd imagegen-mcp-d3
npm install
npm run build
npm start

Prerequisites

• Node.js: Version 18.0.0 or higher.
• OpenAI API Key: You need a valid OpenAI API key with DALL - E 3 access.

Configuration

Environment Variables

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="your-openai-api-key-here"

Or create a .env file in your project root:

OPENAI_API_KEY=your-openai-api-key-here

💻 Usage Examples

Basic Usage

With Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "mcpServers": {
    "imagegen-mcp-d3": {
      "command": "npx",
      "args": ["imagegen-mcp-d3"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

With Other MCP Clients

The server implements the standard MCP protocol and can be used with any compatible client.

Advanced Usage

generate_image

Generates an image using DALL - E 3 and saves it to the specified location.

Parameters:

• prompt (required): Text description of the image to generate.
• output_path (required): Full file path where the image should be saved.
• size (optional): Image dimensions - "1024x1024", "1024x1792", or "1792x1024" (default: "1024x1024").
• quality (optional): Image quality - "standard" or "hd" (default: "hd").
• style (optional): Image style - "vivid" or "natural" (default: "vivid").

Example:

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A serene sunset over a mountain lake with pine trees",
    "output_path": "/Users/username/Pictures/sunset_lake.png",
    "size": "1024x1792",
    "quality": "hd",
    "style": "natural"
  }
}

Response: The tool returns detailed information about the generated image, including:

• Original and revised prompts.
• Image URL.
• File save location.
• Image specifications.
• File size.

📚 Documentation

API Reference

Image Sizes

• Square: 1024x1024 - Perfect for social media and general use.
• Portrait: 1024x1792 - Great for mobile wallpapers and vertical displays.
• Landscape: 1792x1024 - Ideal for desktop wallpapers and horizontal displays.

Quality Options

• Standard: Faster generation, good quality.
• HD: Higher quality with more detail (recommended).

Style Options

• Vivid: More dramatic and artistic interpretations.
• Natural: More realistic and natural - looking results.

🔧 Technical Details

Development

Setup

git clone https://github.com/chrisurf/imagegen-mcp-d3.git
cd imagegen-mcp-d3
npm install

Available Scripts

npm run dev          # Run in development mode with hot reload
npm run build        # Build for production
npm run start        # Start the built server
npm run test         # Run tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier
npm run typecheck    # Run TypeScript type checking

Project Structure

src/
├── index.ts           # Main server implementation
├── types.ts          # TypeScript type definitions
└── __tests__/        # Test files
    └── index.test.ts # Main test suite

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

Error Handling

The server provides comprehensive error handling for common scenarios:

• Missing API Key: Clear error message when OPENAI_API_KEY is not set.
• Invalid Parameters: Validation errors for required and optional parameters.
• API Errors: Detailed error messages from the OpenAI API.
• File System Errors: Handling of directory creation and file writing issues.
• Network Errors: Graceful handling of network connectivity issues.

Logging

The server provides detailed logging for monitoring and debugging:

• Request initiation and parameters.
• API communication status.
• Image generation progress.
• File saving confirmation.
• Error details and stack traces.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Make your changes.
4. Add tests for new functionality.
5. Ensure all tests pass: npm test.
6. Commit your changes: git commit -m 'Add amazing feature'.
7. Push to the branch: git push origin feature/amazing-feature.
8. Open a Pull Request.

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

• Testing: Automated testing on multiple Node.js versions (18, 20, 22).
• Code Quality: ESLint, Prettier, and TypeScript checks.
• Security: Dependency vulnerability scanning.
• Publishing: Automatic NPM publishing on release.
• Coverage: Local code coverage reporting.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Open an issue for support

Changelog

See CHANGELOG.md for a detailed history of changes.

Related Projects

• Model Context Protocol - The official MCP specification.
• MCP TypeScript SDK - TypeScript SDK for MCP.
• Claude Desktop - AI assistant that supports MCP servers.

Acknowledgments

• OpenAI for the DALL - E 3 API.
• Anthropic for the Model Context Protocol specification.
• The MCP community for tools and documentation. High - performance MCP for generating images using DALL·E 3 – optimized for fast, scalable, and customizable inference workflows.