# 🌙 Moondream MCP Server
A powerful Model Context Protocol (MCP) server that brings advanced image analysis capabilities to your applications using the Moondream vision model. This server seamlessly integrates with Claude and Cline, providing a bridge between AI assistants and sophisticated computer vision tasks.
This IS NOT an offical Moondream package. All credit to [moondream.ai](https://github.com/vikhyat/moondream) for making the best open source vision model that you can run on consumer hardware.
<div align="center" style="height: 150px; overflow: hidden; display: flex; align-items: center; margin: 20px 0;">
<img src="https://github.com/user-attachments/assets/e999ada0-9dfa-4f3d-a489-e4ce58434ecb" alt="Moondream MCP Banner" style="width: 100%; object-fit: cover;">
</div>
## ✨ Features
- 🖼️ **Image Captioning**: Generate natural language descriptions of images
- 🔍 **Object Detection**: Identify and locate specific objects within images
- 💭 **Visual Question Answering**: Ask questions about image content and receive intelligent responses
- 🚀 **High Performance**: Uses quantized 8-bit models for efficient inference
- 🔄 **Automatic Setup**: Handles model downloading and environment setup
- 🛠️ **MCP Integration**: Standardized protocol for seamless tool usage
## 🎯 Use Cases
- **Content Analysis**: Automatically generate descriptions for image content
- **Accessibility**: Create alt text for visually impaired users
- **Data Extraction**: Extract specific information from images through targeted questions
- **Object Verification**: Confirm the presence of specific objects in images
- **Scene Understanding**: Analyze complex scenes and their components
## 🚀 Quick Start
### Prerequisites
- Node.js v18 or higher
- Python 3.8+
- UV package manager (automatically installed if not present)
### Installation
1. **Clone and Setup**
```bash
git clone <repository-url>
cd moondream-server
pnpm install
```
2. **Build the Server**
```bash
pnpm run build
```
The server handles the rest automatically:
- Creates Python virtual environment
- Installs UV if not present
- Downloads and sets up the Moondream model
- Manages the model server process
### Integration with Claude/Cline
Add to your MCP settings file (`claude_desktop_config.json` or `cline_mcp_settings.json`):
```json
{
"mcpServers": {
"moondream": {
"command": "node",
"args": ["/path/to/moondream-server/build/index.js"]
}
}
}
```
## 🛠️ Available Tools
### analyze_image
Powerful image analysis tool with multiple modes:
```typescript
{
"name": "analyze_image",
"arguments": {
"image_path": string, // Path to image file
"prompt": string // Analysis command
}
}
```
**Prompt Types:**
- `"generate caption"` - Creates natural language description
- `"detect: [object]"` - Finds specific objects (e.g., "detect: car")
- `"[question]"` - Answers questions about the image
**Examples:**
```javascript
// Image Captioning
{
"image_path": "photo.jpg",
"prompt": "generate caption"
}
// Object Detection
{
"image_path": "scene.jpg",
"prompt": "detect: person"
}
// Visual Q&A
{
"image_path": "painting.jpg",
"prompt": "What colors are used in this painting?"
}
```
## 🔧 Technical Details
### Architecture
The server operates as a dual-component system:
1. **MCP Interface Layer**
- Handles protocol communication
- Manages tool interfaces
- Processes requests/responses
2. **Moondream Model Server**
- Runs the vision model
- Processes image analysis
- Provides HTTP API endpoints
### Model Information
Uses the Moondream quantized model:
- Default: `moondream-2b-int8.mf.gz`
- Efficient 8-bit quantization
- Automatic download from Hugging Face
- ~500MB model size
### Performance
- Fast startup with automatic caching
- Efficient memory usage through quantization
- Responsive API endpoints
- Concurrent request handling
## 🔍 Debugging
Common issues and solutions:
1. **Model Download Issues**
```bash
# Manual model download
wget https://huggingface.co/vikhyatk/moondream2/resolve/main/moondream-0_5b-int4.mf.gz
```
2. **Server Port Conflicts**
- Default port: 3475
- Check for process using: `lsof -i :3475`
3. **Python Environment**
- UV manages dependencies
- Check logs in temp directory
- Virtual env in system temp folder
## 🤝 Contributing
Contributions welcome! Areas of interest:
- Additional model support
- Performance optimizations
- New analysis capabilities
- Documentation improvements
## 📄 License
[Add your license information here]
## 🙏 Acknowledgments
- [Moondream Model Team](https://github.com/vikhyat/moondream)
- Model Context Protocol (MCP) Community
- Contributors and maintainers
---
<p align="center">
Made with ❤️ by Nighttrek
</p>