RichdaleAI MCP - RunPod Image Generation

A Model Context Protocol (MCP) server that integrates with RunPod's Stable Diffusion API to generate AI images from text prompts. Automatically saves generated images with comprehensive metadata and opens them for immediate viewing.

✨ Features

• AI Image Generation - Create images from text prompts using Stable Diffusion
• RunPod Integration - Seamless integration with RunPod's API
• Automatic File Management - Saves images and metadata with consistent naming
• Auto-Open Images - Generated images open automatically in your default viewer
• Comprehensive Metadata - Tracks all generation parameters and RunPod responses
• MCP Protocol - Full compatibility with MCP clients (Claude Desktop, Cursor, etc.)

🚀 Quick Start

Prerequisites

• Node.js 18+
• RunPod Account with API access
• Stable Diffusion Endpoint configured on RunPod

Building

# Clean install dependencies
rm -rf node_modules package-lock.json
npm install

# Test the build
npm start

Publishing

1. Version Management

# Update version before publishing
npm version patch    # 0.1.0 → 0.1.1
npm version minor    # 0.1.0 → 0.2.0
npm version major    # 0.1.0 → 1.0.0

# Or manually edit package.json

2. Publish Commands

# First time publishing
npm publish

# Subsequent updates
npm version patch && npm publish

Installation

# Install globally
npm install -g richdaleai-mcp

# Or use with npx
npx richdaleai-mcp

Environment Variables

Create a .env file or set these environment variables:

# Required
RUNPOD_API_KEY=your_runpod_api_key_here
RUNPOD_ENDPOINT=https://api.runpod.ai/v2/your_endpoint_id/runsync

# Optional
IMAGE_STORAGE_DIRECTORY=C:\Users\username\Downloads\richdaleai-images

🔧 MCP Configuration

Cursor Integration

Add this to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "richdaleai-mcp": {
      "command": "npx",
      "args": ["-y", "richdaleai-mcp"],
      "env": {
        "RUNPOD_API_KEY": "your_runpod_api_key_here",
        "RUNPOD_ENDPOINT": "https://api.runpod.ai/v2/your_endpoint_id/runsync",
        "IMAGE_STORAGE_DIRECTORY": "C:\\Users\\username\\Downloads\\richdaleai-images"
      }
    }
  }
}

Claude Desktop Integration

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "richdaleai-mcp": {
      "command": "npx",
      "args": ["-y", "richdaleai-mcp"],
      "env": {
        "RUNPOD_API_KEY": "your_runpod_api_key_here",
        "RUNPOD_ENDPOINT": "https://api.runpod.ai/v2/your_endpoint_id/runsync"
      }
    }
  }
}

🛠️ Available Tools

generate_image

Generate AI images from text prompts.

Parameters:

• prompt (required): Text description of the image to generate
• negative_prompt (optional): Elements to avoid in the image
• width (optional): Image width in pixels (default: 1024)
• height (optional): Image height in pixels (default: 1024)
• guidance_scale (optional): Generation guidance (default: 3.5)
• denoising_steps (optional): Denoising steps (default: 30)

Example:

Generate an image of a majestic dragon flying over a medieval castle at sunset

health_check

Check server status and configuration.

Returns:

• Server health status
• Configuration details
• RunPod connection status

📁 File Structure

Generated files are saved with consistent naming:

richdaleai-images/
├── generated_20250820_154456_abc123.png
├── generated_20250820_154456_abc123_metadata.json
├── generated_20250820_154457_def456.png
└── generated_20250820_154457_def456_metadata.json

Metadata Contents

Each metadata file contains:

• Generation timestamp
• Image filename
• Original prompt and parameters
• Complete RunPod API response
• Performance metrics (execution time, delay time)
• Job IDs and worker information

🔑 RunPod Setup

1. Create Account: Sign up at runpod.io
2. Deploy Endpoint: Deploy a Stable Diffusion endpoint
3. Get API Key: Generate API key in your account settings
4. Configure Endpoint: Note your endpoint ID for the API URL

📦 Development

Local Development

# Clone repository
git clone https://github.com/Richdale-AI/richdaleai-mcp-npx.git
cd richdaleai-mcp-npx

# Install dependencies
npm install

# Run locally
npm start

# Install globally for testing
npm run dev

Project Structure

richdaleai-mcp-npx/
├── bin/
│   └── cli.js          # CLI entry point
├── server.js            # MCP server implementation
├── utils.js             # Utility functions
├── package.json         # Package configuration
├── LICENSE              # MIT License
└── README.md            # This file

🐛 Troubleshooting

Common Issues

1. "RUNPOD_ENDPOINT and RUNPOD_API_KEY must be set"

   • Ensure environment variables are properly set
   • Check for typos in API key or endpoint URL

2. "Could not open image automatically"

   • This is a warning, not an error
   • Images are still saved successfully
   • Check if your system has a default image viewer

3. "Generation failed"

   • Verify RunPod endpoint is running
   • Check API key permissions
   • Ensure endpoint supports the requested parameters

Debug Mode

Enable verbose logging by setting:

DEBUG=* npx richdaleai-mcp

📄 License

This project is licensed under the GNU Affero General Public License v3 (AGPL-3.0) - see the LICENSE file for details.

Important Note: AGPL-3.0 is a copyleft license that requires any derivative works or network services using this code to also be open source. If you plan to use this code in a commercial application or network service, please review the license terms carefully.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: MCP Protocol
• Repository: GitHub

Made for and by Richdale-AI