{"id":30252143,"url":"https://github.com/colemurray/moondream-mcp","last_synced_at":"2025-08-15T11:13:47.184Z","repository":{"id":302227421,"uuid":"994048130","full_name":"ColeMurray/moondream-mcp","owner":"ColeMurray","description":"Moondream MCP Server in Python","archived":false,"fork":false,"pushed_at":"2025-07-02T16:42:33.000Z","size":84,"stargazers_count":40,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-14T18:12:47.982Z","etag":null,"topics":["mcp","mcp-server","moondream","python"],"latest_commit_sha":null,"homepage":"https://murraycole.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ColeMurray.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-01T04:47:15.000Z","updated_at":"2025-07-12T17:41:37.000Z","dependencies_parsed_at":"2025-07-01T08:44:58.070Z","dependency_job_id":null,"html_url":"https://github.com/ColeMurray/moondream-mcp","commit_stats":null,"previous_names":["colemurray/moondream-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ColeMurray/moondream-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fmoondream-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fmoondream-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fmoondream-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fmoondream-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ColeMurray","download_url":"https://codeload.github.com/ColeMurray/moondream-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fmoondream-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270559173,"owners_count":24606680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","moondream","python"],"created_at":"2025-08-15T11:13:44.165Z","updated_at":"2025-08-15T11:13:47.171Z","avatar_url":"https://github.com/ColeMurray.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Moondream MCP Server\n\nA FastMCP server for [Moondream](https://github.com/vikhyat/moondream), 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).\n\n## Features\n\n- 🖼️ **Image Captioning**: Generate short, normal, or detailed captions for images\n- ❓ **Visual Question Answering**: Ask natural language questions about images\n- 🔍 **Object Detection**: Detect and locate specific objects with bounding boxes\n- 📍 **Visual Pointing**: Get precise coordinates of objects in images\n- 🔗 **URL Support**: Process images from both local files and remote URLs\n- ⚡ **Batch Processing**: Analyze multiple images efficiently\n- 🚀 **Device Optimization**: Automatic detection and optimization for CPU, CUDA, and MPS (Apple Silicon)\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- PyTorch 2.0+ (with appropriate device support)\n\n### Using uvx (Recommended for Claude Desktop)\n\n```bash\n# Run without installation\nuvx moondream-mcp\n\n# Or specify a specific version\nuvx moondream-mcp==1.0.2\n```\n\n### Install from PyPI\n\n```bash\npip install moondream-mcp\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/ColeMurray/moondream-mcp.git\ncd moondream-mcp\npip install -e .\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/ColeMurray/moondream-mcp.git\ncd moondream-mcp\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### Running the Server\n\n```bash\n# Using uvx (no installation needed)\nuvx moondream-mcp\n\n# Using pip-installed command\nmoondream-mcp\n\n# Or run directly with Python\npython -m moondream_mcp.server\n```\n\n### Claude Desktop Integration\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n#### Using uvx (Recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"moondream\": {\n      \"command\": \"uvx\",\n      \"args\": [\"moondream-mcp\"],\n      \"env\": {\n        \"MOONDREAM_DEVICE\": \"auto\"\n      }\n    }\n  }\n}\n```\n\n#### Using pip-installed command\n\n```json\n{\n  \"mcpServers\": {\n    \"moondream\": {\n      \"command\": \"moondream-mcp\",\n      \"env\": {\n        \"MOONDREAM_DEVICE\": \"auto\"\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\nThe server can be configured using environment variables:\n\n### Model Settings\n\n- `MOONDREAM_MODEL_NAME`: Model name (default: `vikhyatk/moondream2`)\n- `MOONDREAM_MODEL_REVISION`: Model revision (default: `2025-01-09`)\n- `MOONDREAM_TRUST_REMOTE_CODE`: Trust remote code (default: `true`)\n\n### Device Settings\n\n- `MOONDREAM_DEVICE`: Force specific device (`cpu`, `cuda`, `mps`, or `auto`)\n\n### Image Processing\n\n- `MOONDREAM_MAX_IMAGE_SIZE`: Maximum image dimensions (default: `2048x2048`)\n- `MOONDREAM_MAX_FILE_SIZE_MB`: Maximum file size in MB (default: `50`)\n\n### Performance\n\n- `MOONDREAM_TIMEOUT_SECONDS`: Processing timeout (default: `120`)\n- `MOONDREAM_MAX_CONCURRENT_REQUESTS`: Max concurrent requests (default: `5`)\n- `MOONDREAM_ENABLE_STREAMING`: Enable streaming for captions (default: `true`)\n- `MOONDREAM_MAX_BATCH_SIZE`: Maximum batch size for batch operations (default: `10`)\n- `MOONDREAM_BATCH_CONCURRENCY`: Concurrent batch processing limit (default: `3`)\n- `MOONDREAM_ENABLE_BATCH_PROGRESS`: Enable progress reporting for batch operations (default: `true`)\n\n### Network (for URLs)\n\n- `MOONDREAM_REQUEST_TIMEOUT_SECONDS`: HTTP request timeout (default: `30`)\n- `MOONDREAM_MAX_REDIRECTS`: Maximum HTTP redirects (default: `5`)\n- `MOONDREAM_USER_AGENT`: HTTP User-Agent header\n\n## Available Tools\n\n### 1. `caption_image`\n\nGenerate captions for images.\n\n**Parameters:**\n- `image_path` (string): Path to image file or URL\n- `length` (string): Caption length - `\"short\"`, `\"normal\"`, or `\"detailed\"`\n- `stream` (boolean): Whether to stream caption generation\n\n**Example:**\n```json\n{\n  \"image_path\": \"https://example.com/image.jpg\",\n  \"length\": \"detailed\",\n  \"stream\": false\n}\n```\n\n### 2. `query_image`\n\nAsk questions about images.\n\n**Parameters:**\n- `image_path` (string): Path to image file or URL\n- `question` (string): Question to ask about the image\n\n**Example:**\n```json\n{\n  \"image_path\": \"/path/to/image.jpg\",\n  \"question\": \"How many people are in this image?\"\n}\n```\n\n### 3. `detect_objects`\n\nDetect specific objects in images.\n\n**Parameters:**\n- `image_path` (string): Path to image file or URL\n- `object_name` (string): Name of object to detect\n\n**Example:**\n```json\n{\n  \"image_path\": \"https://example.com/photo.jpg\",\n  \"object_name\": \"person\"\n}\n```\n\n### 4. `point_objects`\n\nGet coordinates of objects in images.\n\n**Parameters:**\n- `image_path` (string): Path to image file or URL\n- `object_name` (string): Name of object to locate\n\n**Example:**\n```json\n{\n  \"image_path\": \"/path/to/image.jpg\",\n  \"object_name\": \"car\"\n}\n```\n\n### 5. `analyze_image`\n\nMulti-purpose image analysis tool.\n\n**Parameters:**\n- `image_path` (string): Path to image file or URL\n- `operation` (string): Operation type (`\"caption\"`, `\"query\"`, `\"detect\"`, `\"point\"`)\n- `parameters` (string): JSON string with operation-specific parameters\n\n**Example:**\n```json\n{\n  \"image_path\": \"https://example.com/image.jpg\",\n  \"operation\": \"query\",\n  \"parameters\": \"{\\\"question\\\": \\\"What is the weather like?\\\"}\"\n}\n```\n\n### 6. `batch_analyze_images`\n\nProcess multiple images in batch.\n\n**Parameters:**\n- `image_paths` (string): JSON array of image paths\n- `operation` (string): Operation to perform on all images\n- `parameters` (string): JSON string with operation-specific parameters\n\n**Example:**\n```json\n{\n  \"image_paths\": \"[\\\"image1.jpg\\\", \\\"image2.jpg\\\"]\",\n  \"operation\": \"caption\",\n  \"parameters\": \"{\\\"length\\\": \\\"short\\\"}\"\n}\n```\n\n## Usage Examples\n\n### Basic Image Captioning\n\n```python\n# Using the caption_image tool\nresult = await caption_image(\n    image_path=\"https://example.com/sunset.jpg\",\n    length=\"detailed\"\n)\n```\n\n### Visual Question Answering\n\n```python\n# Ask about image content\nresult = await query_image(\n    image_path=\"/path/to/family_photo.jpg\",\n    question=\"How many children are in this photo?\"\n)\n```\n\n### Object Detection\n\n```python\n# Detect faces in an image\nresult = await detect_objects(\n    image_path=\"https://example.com/group_photo.jpg\",\n    object_name=\"face\"\n)\n```\n\n### Batch Processing\n\n```python\n# Process multiple images\nresult = await batch_analyze_images(\n    image_paths='[\"img1.jpg\", \"img2.jpg\", \"img3.jpg\"]',\n    operation=\"caption\",\n    parameters='{\"length\": \"normal\"}'\n)\n```\n\n## Device Support\n\nThe server automatically detects and optimizes for available hardware:\n\n### Apple Silicon (MPS)\n- Optimal performance on M1/M2/M3 Macs\n- Automatic memory management\n- Native acceleration\n\n### NVIDIA CUDA\n- GPU acceleration for NVIDIA cards\n- Automatic CUDA memory management\n- Mixed precision support\n\n### CPU Fallback\n- Works on any system\n- Optimized for multi-core processing\n- Lower memory requirements\n\n## Error Handling\n\nThe server provides detailed error information:\n\n```json\n{\n  \"success\": false,\n  \"error_message\": \"Image file not found: /path/to/missing.jpg\",\n  \"error_code\": \"IMAGE_PROCESSING_ERROR\",\n  \"processing_time_ms\": 15.2\n}\n```\n\nCommon error codes:\n- `MODEL_LOAD_ERROR`: Issues loading the Moondream model\n- `IMAGE_PROCESSING_ERROR`: Problems with image files or URLs\n- `INFERENCE_ERROR`: Model inference failures\n- `INVALID_REQUEST`: Invalid parameters or requests\n\n## Performance Tips\n\n1. **Use appropriate image sizes**: Resize large images before processing\n2. **Batch processing**: Use `batch_analyze_images` for multiple images\n3. **Device optimization**: Let the server auto-detect the best device\n4. **Concurrent requests**: Adjust `MOONDREAM_MAX_CONCURRENT_REQUESTS` based on your hardware\n5. **Memory management**: Monitor memory usage, especially with large images\n\n## Troubleshooting\n\n### Model Loading Issues\n\n```bash\n# Check PyTorch installation\npython -c \"import torch; print(torch.__version__)\"\n\n# Check device availability\npython -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}, MPS: {torch.backends.mps.is_available()}')\"\n```\n\n### Memory Issues\n\n- Reduce `MOONDREAM_MAX_IMAGE_SIZE`\n- Lower `MOONDREAM_MAX_CONCURRENT_REQUESTS`\n- Use CPU instead of GPU for large images\n\n### Network Issues\n\n- Check firewall settings for URL access\n- Increase `MOONDREAM_REQUEST_TIMEOUT_SECONDS`\n- Verify SSL certificates for HTTPS URLs\n\n## Development\n\n### Running Tests\n\n```bash\npytest tests/\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Sort imports\nisort src/ tests/\n\n# Type checking\nmypy src/\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run quality checks\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [Moondream](https://github.com/vikhyat/moondream) - The amazing vision language model\n- [FastMCP](https://github.com/jlowin/fastmcp) - The MCP server framework\n- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification\n\n## Support\n\n- 📖 [Documentation](https://github.com/ColeMurray/moondream-mcp#readme)\n- 🐛 [Issue Tracker](https://github.com/ColeMurray/moondream-mcp/issues)\n- 💬 [Discussions](https://github.com/ColeMurray/moondream-mcp/discussions)\n\n---\n\n**Note**: This server requires downloading the Moondream model on first use, which may take some time depending on your internet connection. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolemurray%2Fmoondream-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolemurray%2Fmoondream-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolemurray%2Fmoondream-mcp/lists"}