dreamtail-mcp/README.md

🎨 DreamTail MCP Server

Model Context Protocol (MCP) server for integrating DreamTail SDXL image generation with Claude Desktop.

Overview

This MCP server exposes DreamTail's Stable Diffusion XL image generation capabilities to Claude Desktop through a single, simple tool: dreamtail_generate().

Features:

• 🎨 Generate high-quality 1024x1024 images using SDXL
• 🖼️ Inline image display in Claude Desktop (new!)
• ⏱️ Automatic job submission and polling (no manual checking)
• 💾 Automatic download to local folder (configurable)
• 🗜️ Smart format conversion with adaptive compression for 1MB limit
• 🔄 Built-in progress tracking and timeout handling
• 💬 Natural language prompts via Claude
• ⚡ Powered by Jetson AGX Orin GPU

Prerequisites

1. DreamTail service running on bigorin:8765
2. Python 3.8+ installed
3. Claude Desktop installed

Installation

1. Install Dependencies

cd /home/alex/Projects/dreamtail-mcp
pip install -r requirements.txt

Or using uv (recommended):

uv pip install -r requirements.txt

2. Make Script Executable

chmod +x dreamtail_mcp.py

3. Test the Server Locally

# Test that the server starts without errors
python3 dreamtail_mcp.py
# Press Ctrl+C to stop

Claude Desktop Configuration

Step 1: Locate Configuration File

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Or use Claude Desktop:

• Open Claude Desktop
• Go to: Settings → Developer → "Edit Config"

Step 2: Add DreamTail MCP Server

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "dreamtail": {
      "command": "python3",
      "args": [
        "/home/alex/Projects/dreamtail-mcp/dreamtail_mcp.py"
      ],
      "env": {
        "DREAMTAIL_BASE_URL": "http://192.168.50.30:8765",
        "DREAMTAIL_DOWNLOAD_DIR": "/Users/yourname/Pictures/dreamtail",
        "DREAMTAIL_FORMAT": "jpeg",
        "DREAMTAIL_JPEG_QUALITY": "95",
        "DREAMTAIL_INLINE_DISPLAY": "true",
        "DREAMTAIL_INLINE_QUALITY": "85"
      }
    }
  }
}

Important notes:

• Use the absolute path to dreamtail_mcp.py
• Use the IP address for DREAMTAIL_BASE_URL instead of hostname (e.g., 192.168.50.30:8765 instead of bigorin:8765)
• Set DREAMTAIL_DOWNLOAD_DIR to your preferred download location (defaults to ~/dreamtail_images)
• DREAMTAIL_FORMAT options: "jpeg" (default), "png", or "both" - for saved files
• DREAMTAIL_JPEG_QUALITY: 1-100 (default: 95) - quality for saved files
• DREAMTAIL_INLINE_DISPLAY: "true" (default) or "false" - enable inline image display in Claude Desktop
• DREAMTAIL_INLINE_QUALITY: 1-100 (default: 85) - JPEG quality for inline display (lower = smaller file for 1MB limit)
• If you have other MCP servers configured, add the "dreamtail" entry alongside them

Step 3: Restart Claude Desktop

You MUST completely quit and restart Claude Desktop for the changes to take effect:

macOS:

# Quit Claude Desktop completely
# Then reopen from Applications

Step 4: Verify Installation

1. Open Claude Desktop
2. Look for the 🔨 (hammer) icon in the bottom-right corner of the chat input
3. Click it to see available tools
4. You should see "DreamTail Image Generator" with the dreamtail_generate tool

Usage

Once configured, you can ask Claude to generate images naturally:

Example Prompts

Basic generation:

Generate an image of a serene mountain landscape at sunset

With negative prompt:

Create an image of a cat wearing a wizard hat, but avoid any blurry or
low-quality elements

Custom dimensions:

Generate a 512x512 image of a futuristic cityscape

More inference steps for quality:

Create a highly detailed portrait of a robot, using 50 inference steps

What Claude Will Do

1. Parse your natural language request
2. Call dreamtail_generate() with appropriate parameters
3. Wait ~45-60 seconds while the image generates
4. Display the image inline in the chat (when enabled)
5. Automatically save full-resolution version to your local folder

Response Format

With inline display enabled (default):

Claude will show the generated image directly in the conversation! No need to open files or URLs - the image appears immediately for analysis and discussion.

The image displayed inline is:

• Compressed JPEG at quality 85 (or lower if needed to fit 1MB limit)
• May be slightly resized if the original is too large
• Optimized for fast loading while maintaining visual quality

Full-resolution files are saved to disk:

• Location: ~/dreamtail_images/{job_id}.jpg (and .png if configured)
• Quality: Your configured JPEG quality (default 95) or original PNG
• Use these for high-quality archival or further editing

With inline display disabled:

Claude will provide a text message:

Image generated successfully!
Saved to: /Users/yourname/Pictures/dreamtail/{job_id}.jpg

You can then open the file directly from your local filesystem.

Tool Reference

dreamtail_generate()

Parameters:

Parameter	Type	Default	Description
prompt	string	required	Text description of image to generate
negative_prompt	string	None	What to avoid in the image (optional)
width	integer	1024	Image width (must be multiple of 8)
height	integer	1024	Image height (must be multiple of 8)
num_inference_steps	integer	30	Denoising steps (20-50, higher = better quality but slower)
client_id	string	"claude"	Client identifier

Returns:

{
    "status": "completed",  # or "failed", "timeout", "error"
    "job_id": "uuid",
    "image_url": "http://192.168.50.30:8765/result/{job_id}",
    "local_paths": ["/path/to/download/dir/{job_id}.jpg"],  # List of saved files
    "progress": 100,
    "message": "Image generated successfully! Saved to: /path/to/download/dir/{job_id}.jpg"
}

Notes:

• local_paths contains 1 file (JPEG or PNG) or 2 files (when DREAMTAIL_FORMAT="both")
• JPEG files are optimized and ~10x smaller than PNG with negligible quality loss at 95%

Generation Time:

• Typical: ~45-60 seconds for 1024x1024 @ 30 steps
• Fast: ~30-40 seconds for 20 steps or 512x512
• High quality: ~60-90 seconds for 50 steps

Troubleshooting

Tool Not Appearing in Claude Desktop

1. Check config path: Ensure you're editing the correct config file
2. Verify absolute path: Must be absolute, not relative (e.g., /home/alex/... not ~/...)
3. Restart Claude: Completely quit and reopen Claude Desktop
4. Check logs: Look for errors in Claude Desktop's logs

"Failed to connect to DreamTail"

1. Check DreamTail is running:

   curl http://bigorin:8765/health
   

2. Verify network access: Ensure your machine can reach bigorin:8765

3. Update config: Check DREAMTAIL_BASE_URL in Claude config

"Generation exceeded timeout"

• Normal generation takes 45-60 seconds
• If you get timeouts, DreamTail might be overloaded or having issues
• Check DreamTail logs: ssh bigorin "sudo docker logs dreamtail"

Import Errors

# Reinstall dependencies
cd /home/alex/Projects/dreamtail-mcp
pip install --upgrade -r requirements.txt

Advanced Configuration

Inline Display Options

Control how images are displayed in Claude Desktop:

"env": {
  "DREAMTAIL_INLINE_DISPLAY": "true",
  "DREAMTAIL_INLINE_QUALITY": "85"
}

Options:

• DREAMTAIL_INLINE_DISPLAY: "true" (default) or "false"
  • "true": Images display inline in Claude Desktop (recommended)
  • "false": Return text message with file path only
• DREAMTAIL_INLINE_QUALITY: 50-95 (default: 85)
  • JPEG compression quality for inline display
  • Lower values = smaller files (required for 1MB limit)
  • 85: Good balance of quality and size (~150-300KB)
  • 70-75: More aggressive compression for large images
  • Will automatically reduce if image still exceeds 1MB

Why inline quality is lower than saved quality:

• Claude Desktop has a 1MB limit for tool responses
• Images must be compressed to fit this limit
• Full-resolution images are always saved to disk at your configured quality
• You get the best of both worlds: instant viewing + high-quality archives

Image Format Options

Control saved file format in your Claude Desktop config:

"env": {
  "DREAMTAIL_BASE_URL": "http://192.168.50.30:8765",
  "DREAMTAIL_DOWNLOAD_DIR": "/Users/yourname/Pictures/dreamtail",
  "DREAMTAIL_FORMAT": "jpeg",
  "DREAMTAIL_JPEG_QUALITY": "95"
}

Format Options:

• "jpeg" (default): Save as JPEG at specified quality
  • Quality 95: Visually lossless, ~10x smaller than PNG
  • Quality 85: Very good, ~15x smaller than PNG
  • Quality 75: Good for web, ~20x smaller than PNG
• "png": Save as PNG (lossless, ~2-5MB per image)
• "both": Save both JPEG and PNG versions

File Size Comparison (1024x1024):

• PNG: ~2-5MB
• JPEG Q95: ~200-500KB (recommended)
• JPEG Q85: ~150-300KB
• JPEG Q75: ~100-200KB

Custom Download Directory

Tip: Use an absolute path, not ~. For example:

• ✅ /Users/alex/Pictures/dreamtail
• ✅ /home/alex/dreamtail_images
• ❌ ~/Pictures/dreamtail (may not expand correctly in Claude Desktop)

If not specified, images will be saved to ~/dreamtail_images by default.

Custom Timeout

Edit dreamtail_mcp.py and change:

DEFAULT_TIMEOUT = 180  # 3 minutes instead of 2

Different DreamTail Instance

In Claude Desktop config:

"env": {
  "DREAMTAIL_BASE_URL": "http://192.168.50.30:8765"
}

Using uv (Python Package Manager)

In Claude Desktop config:

{
  "mcpServers": {
    "dreamtail": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/alex/Projects/dreamtail-mcp",
        "run",
        "dreamtail_mcp.py"
      ],
      "env": {
        "DREAMTAIL_BASE_URL": "http://bigorin:8765"
      }
    }
  }
}

Architecture

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ stdio (MCP)
         ▼
┌─────────────────┐
│ dreamtail_mcp   │ (this server)
└────────┬────────┘
         │ HTTP REST
         ▼
┌─────────────────┐
│   DreamTail     │ (bigorin:8765)
│   SDXL Service  │
└─────────────────┘

Flow:

1. User asks Claude to generate an image
2. Claude calls dreamtail_generate() via MCP
3. MCP server submits job to DreamTail API
4. MCP server polls status every 3 seconds
5. When complete, downloads image to local folder
6. Claude shows the user the local file path

Related Projects

• DreamTail: SDXL image generation service (../dreamtail)
• Lyra: AI assistant ecosystem
• Model Context Protocol: https://modelcontextprotocol.io

License

Part of the Lyra project ecosystem.

---

Built with ❤️ for Claude Desktop integration