Initial commit: DreamTail MCP client
🎨 MCP integration for DreamTail (SDXL on Jetson Orin) - dreamtail_generate: Create images with prompts - dreamtail_get_info: Get last generated image path - Inline display support for Claude Desktop - Configurable JPEG quality and download directory Built with love for the hardware dragon 🦊
This commit is contained in:
Alex Kazaiev
394
README.md
Executable file
394
README.md
Executable file
@@ -0,0 +1,394 @@
|
||||
# 🎨 DreamTail MCP Server
|
||||
|
||||
Model Context Protocol (MCP) server for integrating [DreamTail](../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
|
||||
|
||||
```bash
|
||||
cd /home/alex/Projects/dreamtail-mcp
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Or using `uv` (recommended):
|
||||
|
||||
```bash
|
||||
uv pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. Make Script Executable
|
||||
|
||||
```bash
|
||||
chmod +x dreamtail_mcp.py
|
||||
```
|
||||
|
||||
### 3. Test the Server Locally
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
~/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`:
|
||||
|
||||
```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:**
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```python
|
||||
{
|
||||
"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**:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```json
|
||||
"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:
|
||||
|
||||
```json
|
||||
"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:
|
||||
```python
|
||||
DEFAULT_TIMEOUT = 180 # 3 minutes instead of 2
|
||||
```
|
||||
|
||||
### Different DreamTail Instance
|
||||
|
||||
In Claude Desktop config:
|
||||
```json
|
||||
"env": {
|
||||
"DREAMTAIL_BASE_URL": "http://192.168.50.30:8765"
|
||||
}
|
||||
```
|
||||
|
||||
### Using uv (Python Package Manager)
|
||||
|
||||
In Claude Desktop config:
|
||||
```json
|
||||
{
|
||||
"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**
|
||||
Reference in New Issue
Block a user