moondream

Moondream MCP Server exposes image analysis capabilities via the Model Context Protocol. It supports caption generation, visual question answering, object detection, and visual pointing, with support for processing images from local files or remote URLs. The server can handle single-image requests or batch operations, and automatically optimizes for the available device (CPU, CUDA, or MPS). Use the provided tools to perform targeted analyses or combine operations through the multi-tool workflow. For Claude Desktop integration, point your MCP configuration to the moondream-mcp entry so Claude can send image tasks directly to the server.

Prerequisites:

• Python 3.10 or higher
• PyTorch 2.0+ with appropriate device support

Installation steps (recommended paths):

1. Install via uvx (recommended for quick start):

uvx moondream-mcp

2. Install from PyPI (if you have Python/zip installs):

pip install moondream-mcp

3. Install from Source (development or local edits):

git clone https://github.com/vikhyat/moondream-mcp.git
cd moondream-mcp
pip install -e .

4. Development Installation (live code + dev dependencies):

git clone https://github.com/vikhyat/moondream-mcp.git
cd moondream-mcp
pip install -e ".[dev]"

Quick Start (running the server):

# Using uvx (no installation needed)
uvx moondream-mcp

# Using pip-installed command
moondream-mcp

# Or run directly with Python
python -m moondream_mcp.server

Environment variables and configuration:

• MOONDREAM_MODEL_NAME: default vikhyatk/moondream2
• MOONDREAM_MODEL_REVISION: default 2025-01-09
• MOONDREAM_TRUST_REMOTE_CODE: default true
• MOONDREAM_DEVICE: auto/cpu/cuda/mps
• MOONDREAM_MAX_IMAGE_SIZE: default 2048x2048
• MOONDREAM_MAX_FILE_SIZE_MB: default 50
• MOONDREAM_TIMEOUT_SECONDS: default 120
• MOONDREAM_MAX_CONCURRENT_REQUESTS: default 5
• MOONDREAM_ENABLE_STREAMING: default true
• MOONDREAM_MAX_BATCH_SIZE: default 10
• MOONDREAM_BATCH_CONCURRENCY: default 3
• MOONDREAM_ENABLE_BATCH_PROGRESS: default true
• MOONDREAM_REQUEST_TIMEOUT_SECONDS: default 30
• MOONDREAM_MAX_REDIRECTS: default 5
• MOONDREAM_USER_AGENT: optional HTTP User-Agent string for URL requests

Troubleshooting tips:

• Ensure Python 3.10+ is used and PyTorch is properly installed for your device.
• If MOONDREAM_DEVICE auto-detection fails, explicitly set MOONDREAM_DEVICE to cpu/cuda/mps.
• When using batch operations, verify MOONDREAM_MAX_BATCH_SIZE and MOONDREAM_BATCH_CONCURRENCY align with hardware limits.
• Verify network access and URL handling if processing remote images; check MOONDREAM_REQUEST_TIMEOUT_SECONDS and MOONDREAM_MAX_REDIRECTS.

Common issues often relate to model loading or device availability. Check logs for MODEL_LOAD_ERROR or INFERENCE_ERROR, and ensure you have the correct PyTorch and CUDA/MPS setup for your hardware.