@gdm-pixel/leonardo-mcp

🔐 Subscription-Based MCP Server for Leonardo.AI

AI image generation with automatic optimization and FTP upload.

⚠️ Requires Nova-Mind Cloud subscription - Starting at €39/month
⚠️ Unofficial package - Not affiliated with Leonardo.AI

💎 Why Subscription-Required?

Open-source code + Cloud infrastructure model (like Supabase, Vercel)

✅ Code is open - Audit, learn, modify freely
🔐 Usage requires subscription - Backend authentication & services

What you get with subscription:

• 🔑 Secure API key management
• 📊 Usage tracking and rate limiting
• 🧠 Cloud memory and context
• 🔄 Automatic updates
• 💬 Professional support

👉 View pricing & subscribe

📄 Subscription Plans

| Plan | Price | Best For | |------|-------|----------| | 🌱 Nova Mind | €39/month | Personal projects | | 🚀 Nova Pro | €89/month | Professional use | | 💼 Nova Business | €149/month | Teams & priority support |

No free tier available - All features require active subscription.

✨ Features

• 🎨 AI Image Generation - Generate images with Leonardo.AI's powerful models
• 🖼️ Character & Style References - Use reference images for consistent character/style
• 📤 Auto FTP Upload - Automatic upload to your FTP server
• ⚡ Smart Optimization - WebP + JPEG formats with compression
• 🎭 Multiple Models - Phoenix, Kino XL, Anime XL, FLUX, and more
• 🔗 Instant URLs - Get public URLs immediately after generation

📦 Installation

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "leonardo-mcp": {
      "command": "npx",
      "args": ["-y", "@gdm-pixel/leonardo-mcp@latest"],
      "env": {
        "LEONARDO_API_KEY": "your-leonardo-api-key",
        "LEONARDO_OUTPUT_DIR": "C:\\path\\to\\output",
        "FTP_HOST": "ftp.your-server.com",
        "FTP_USER": "your-username",
        "FTP_PASSWORD": "your-password",
        "FTP_PORT": "21",
        "FTP_TARGET_DIR": "/images/",
        "FTP_PUBLIC_URL": "https://your-domain.com/images/"
      }
    }
  }
}

Config location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

⚙️ Configuration

Required Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | LEONARDO_API_KEY | Your Leonardo.AI API key | abcd-1234-... |

Optional Environment Variables (FTP Upload)

| Variable | Description | Example | |----------|-------------|---------| | FTP_HOST | FTP server hostname | ftp.example.com | | FTP_USER | FTP username | [email protected] | | FTP_PASSWORD | FTP password | your-password | | FTP_PORT | FTP port | 21 | | FTP_TARGET_DIR | Target directory | /public/img/ | | FTP_PUBLIC_URL | Public URL base | https://example.com/img/ | | LEONARDO_OUTPUT_DIR | Local output directory | C:\images |

Note: FTP variables are optional. Without them, images are only saved locally.

Getting Your Leonardo.AI API Key

1. Log in to Leonardo.AI
2. Go to User Menu → API Access
3. Generate your API key
4. Copy and paste into your config

🚀 Usage

Generate an Image

Generate an image of a futuristic city at sunset

What happens:

1. Image generated with Leonardo.AI
2. Saved locally (JPEG + WebP formats)
3. Uploaded to FTP (if configured)
4. Public URLs returned

Use Character Reference

Generate a portrait using this character reference: /path/to/character.jpg

Features:

• Maintain consistent character across generations
• Adjustable strength: Low, Mid, High
• Works with Phoenix and Kino XL models

Use Style Reference

Generate a landscape with this style reference: /path/to/style.jpg

Features:

• Apply artistic style from reference image
• Adjustable strength: Low, Mid, High
• Compatible with most models

Upload Reference Image

Upload this image as a character reference: /path/to/image.jpg

Use cases:

• Prepare reference images for future generations
• Store character/style references on Leonardo.AI
• Get shareable reference URLs

🎨 Available Models

| Model | Best For | Code | |-------|----------|------| | Phoenix | General purpose, photorealistic | phoenix | | Kino XL | Cinematic, film-like quality | kino_xl | | Anime XL | Anime and manga style | anime_xl | | FLUX Dev | Experimental, cutting-edge | flux_dev | | FLUX Schnell | Fast generation | flux_schnell | | Leonardo Lightning | Speed-optimized | leonardo_lightning |

📋 Available Tools

generate_image

Generate an AI image with Leonardo.AI.

Parameters:

• prompt (required) - Image description
• model (optional) - Model to use (default: phoenix)
• dimensions (optional) - Image size (default: 1472x832)
• style (optional) - Style preset (default: professional)
• characterReferenceUrl (optional) - Character reference image URL
• characterStrength (optional) - Reference strength: Low, Mid, High
• styleReferenceUrl (optional) - Style reference image URL
• styleStrength (optional) - Reference strength: Low, Mid, High
• filename (optional) - Custom filename
• outputPath (optional) - Custom output path

upload_image_reference

Upload an image to Leonardo.AI as a reference.

Parameters:

• imagePath (required) - Local path to image
• referenceType (optional) - character or style (default: character)

get_user_info

Get your Leonardo.AI account information.

list_models

List available Leonardo.AI models.

Parameters:

• platform (optional) - Filter: all, core, custom (default: all)

get_generation_status

Check status of a generation.

Parameters:

• generationId (required) - Leonardo.AI generation ID

optimize_image

Optimize an image with Sharp (WebP conversion, resizing).

Parameters:

• inputPath (required) - Path to image
• width (optional) - Target width (default: 1280)
• height (optional) - Target height (default: 720)
• quality (optional) - WebP quality 1-100 (default: 85)
• outputPath (optional) - Custom output path

🔧 Troubleshooting

Generation Fails

Problem: "Generation failed" or timeout errors

Solutions:

• Verify your Leonardo.AI API key is valid
• Check your Leonardo.AI account has available tokens
• Ensure prompt follows Leonardo.AI content guidelines
• Try a different model if one fails
• Check Leonardo.AI service status

FTP Upload Issues

Problem: Generation works but FTP upload fails

Solutions:

• Verify all FTP environment variables are set
• Test FTP connection independently
• Check FTP credentials and permissions
• Ensure target directory exists on FTP server
• Images are still saved locally even if FTP fails

Reference Images Not Working

Problem: Character/Style reference doesn't apply

Solutions:

• Ensure reference image is uploaded to Leonardo.AI first
• Use upload_image_reference tool before generation
• Verify reference URL is valid and accessible
• Try adjusting reference strength (Low → High)
• Check model supports references (Phoenix, Kino XL work best)

API Rate Limiting

Problem: "Too many requests" errors

Solutions:

• Wait between generation requests
• Check your Leonardo.AI plan limits
• Monitor token usage with get_user_info
• Consider upgrading Leonardo.AI subscription

💡 Pro Tips

Optimal Prompts

• Be specific and descriptive
• Include style, lighting, and mood
• Mention artistic techniques or references
• Use negative prompts for unwanted elements

Character Consistency

1. Upload character reference once
2. Use same reference URL for all generations
3. Set strength to "High" for maximum consistency
4. Keep prompt details consistent

Best Dimensions

• Landscape: 1472x832 (16:9)
• Portrait: 832x1472 (9:16)
• Square: 1024x1024 (1:1)
• Widescreen: 1792x1024 (21:9)

📄 License

Nova-Mind Cloud License (NMCL) © Charles Annoni - Free for personal use, commercial use requires subscription.

🔗 Links

• NPM Package
• Leonardo.AI Official Site
• Report Issues
• MCP Documentation

🙏 Credits

Created by Charles Annoni (GDM-Pixel)

Part of the Nova-Mind ecosystem - AI-powered coaching platform.