Moondream

A FastMCP server forMoondream, an AI vision language model. This server provides image analysis capabilities including captioning, visual question answering, object detection, and visual pointing through the Model Context Protocol (MCP).

# Run without installation uvx moondream-mcp # Or specify a specific version uvx moondream-mcp==1.0.2

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

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

# Using uvx (no installation needed) uvx moondream-mcp # Using pip-installed command moondream-mcp # Or run directly with Python python -m moondream_mcp.server

Add to your Claude Desktop configuration file:

macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "moondream": { "command": "uvx", "args": ["moondream-mcp"], "env": { "MOONDREAM_DEVICE": "auto" } } } }

{ "mcpServers": { "moondream": { "command": "moondream-mcp", "env": { "MOONDREAM_DEVICE": "auto" } } } }

The server can be configured using environment variables:

- MOONDREAM_MODEL_NAME: Model name (default:vikhyatk/moondream2)
- MOONDREAM_MODEL_REVISION: Model revision (default:2025-01-09)
- MOONDREAM_TRUST_REMOTE_CODE: Trust remote code (default:true)

- MOONDREAM_DEVICE: Force specific device (cpu,cuda,mps, orauto)

- MOONDREAM_MAX_IMAGE_SIZE: Maximum image dimensions (default:2048x2048)
- MOONDREAM_MAX_FILE_SIZE_MB: Maximum file size in MB (default:50)

- MOONDREAM_TIMEOUT_SECONDS: Processing timeout (default:120)
- MOONDREAM_MAX_CONCURRENT_REQUESTS: Max concurrent requests (default:5)
- MOONDREAM_ENABLE_STREAMING: Enable streaming for captions (default:true)
- MOONDREAM_MAX_BATCH_SIZE: Maximum batch size for batch operations (default:10)
- MOONDREAM_BATCH_CONCURRENCY: Concurrent batch processing limit (default:3)
- MOONDREAM_ENABLE_BATCH_PROGRESS: Enable progress reporting for batch operations (default:true)

- MOONDREAM_REQUEST_TIMEOUT_SECONDS: HTTP request timeout (default:30)
- MOONDREAM_MAX_REDIRECTS: Maximum HTTP redirects (default:5)
- MOONDREAM_USER_AGENT: HTTP User-Agent header

- image_path(string): Path to image file or URL
- length(string): Caption length -"short","normal", or"detailed"
- stream(boolean): Whether to stream caption generation

{ "image_path": "https://example.com/image.jpg", "length": "detailed", "stream": false }

- image_path(string): Path to image file or URL
- question(string): Question to ask about the image

{ "image_path": "/path/to/image.jpg", "question": "How many people are in this image?" }

- image_path(string): Path to image file or URL
- object_name(string): Name of object to detect

{ "image_path": "https://example.com/photo.jpg", "object_name": "person" }

- image_path(string): Path to image file or URL
- object_name(string): Name of object to locate

{ "image_path": "/path/to/image.jpg", "object_name": "car" }

- image_path(string): Path to image file or URL
- operation(string): Operation type ("caption","query","detect","point")
- parameters(string): JSON string with operation-specific parameters

{ "image_path": "https://example.com/image.jpg", "operation": "query", "parameters": "{\"question\": \"What is the weather like?\"}" }

- image_paths(string): JSON array of image paths
- operation(string): Operation to perform on all images
- parameters(string): JSON string with operation-specific parameters

{ "image_paths": "[\"image1.jpg\", \"image2.jpg\"]", "operation": "caption", "parameters": "{\"length\": \"short\"}" }

# Using the caption_image tool result = await caption_image( image_path="https://example.com/sunset.jpg", length="detailed" )

# Ask about image content result = await query_image( image_path="/path/to/family_photo.jpg", question="How many children are in this photo?" )

# Detect faces in an image result = await detect_objects( image_path="https://example.com/group_photo.jpg", object_name="face" )

# Process multiple images result = await batch_analyze_images( image_paths='["img1.jpg", "img2.jpg", "img3.jpg"]', operation="caption", parameters='{"length": "normal"}' )

The server automatically detects and optimizes for available hardware:

- Optimal performance on M1/M2/M3 Macs
- Automatic memory management
- Native acceleration

- GPU acceleration for NVIDIA cards
- Automatic CUDA memory management
- Mixed precision support

- Works on any system
- Optimized for multi-core processing
- Lower memory requirements

The server provides detailed error information:

{ "success": false, "error_message": "Image file not found: /path/to/missing.jpg", "error_code": "IMAGE_PROCESSING_ERROR", "processing_time_ms": 15.2 }

- MODEL_LOAD_ERROR: Issues loading the Moondream model
- IMAGE_PROCESSING_ERROR: Problems with image files or URLs
- INFERENCE_ERROR: Model inference failures
- INVALID_REQUEST: Invalid parameters or requests
- Use appropriate image sizes: Resize large images before processing
- Batch processing: Usebatch_analyze_imagesfor multiple images
- Device optimization: Let the server auto-detect the best device
- Concurrent requests: AdjustMOONDREAM_MAX_CONCURRENT_REQUESTSbased on your hardware
- Memory management: Monitor memory usage, especially with large images

# Check PyTorch installation python -c "import torch; print(torch.__version__)" # Check device availability python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, MPS: {torch.backends.mps.is_available()}')"

- ReduceMOONDREAM_MAX_IMAGE_SIZE
- LowerMOONDREAM_MAX_CONCURRENT_REQUESTS
- Use CPU instead of GPU for large images

- Check firewall settings for URL access
- IncreaseMOONDREAM_REQUEST_TIMEOUT_SECONDS
- Verify SSL certificates for HTTPS URLs

# Format code black src/ tests/ # Sort imports isort src/ tests/ # Type checking mypy src/

- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Run quality checks
- Submit a pull request

This project is licensed under the MIT License. SeeLICENSEfor details.

- Moondream- The amazing vision language model
- FastMCP- The MCP server framework
- Model Context Protocol- The protocol specification

- 📖Documentation
- 🐛Issue Tracker
- 💬Discussions

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB