🌙 Moondream MCP 服务器

一个强大的模型上下文协议 (MCP) 服务器，它使用 Moondream 视觉模型为您的应用程序带来高级图像分析功能。该服务器与 Claude 和 Cline 无缝集成，在 AI 助手和复杂的计算机视觉任务之间架起了一座桥梁。

这不是一个官方的 Moondream 包。所有功劳归于 moondream.ai，感谢他们制作了最好的开源视觉模型，您可以在消费级硬件上运行它。

<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>

✨ 特性

• 🖼️ 图像描述: 生成图像的自然语言描述
• 🔍 物体检测: 识别和定位图像中的特定物体
• 💭 视觉问答: 提出关于图像内容的问题并获得智能回复
• 🚀 高性能: 使用量化的 8 位模型进行高效推理
• 🔄 自动设置: 处理模型下载和环境设置
• 🛠️ MCP 集成: 用于无缝工具使用的标准化协议

🎯 使用场景

• 内容分析: 自动生成图像内容的描述
• 可访问性: 为视障用户创建替代文本
• 数据提取: 通过有针对性的问题从图像中提取特定信息
• 物体验证: 确认图像中是否存在特定物体
• 场景理解: 分析复杂场景及其组成部分

🚀 快速开始

前提条件

• Node.js v18 或更高版本
• Python 3.8+
• UV 包管理器（如果不存在，则自动安装）

安装

1. 克隆和设置

git clone <repository-url>
cd moondream-server
pnpm install

2. 构建服务器

pnpm run build

服务器会自动处理其余事项：

• 创建 Python 虚拟环境
• 安装 UV（如果不存在）
• 下载并设置 Moondream 模型
• 管理模型服务器进程

与 Claude/Cline 集成

添加到您的 MCP 配置文件 (claude_desktop_config.json 或 cline_mcp_settings.json):

{
  "mcpServers": {
    "moondream": {
      "command": "node",
      "args": ["/path/to/moondream-server/build/index.js"]
    }
  }
}

🛠️ 可用工具

analyze_image

强大的图像分析工具，具有多种模式：

{
  "name": "analyze_image",
  "arguments": {
    "image_path": string,  // 图像文件路径
    "prompt": string       // 分析命令
  }
}

Prompt 类型:

• "generate caption" - 创建自然语言描述
• "detect: [object]" - 查找特定物体 (例如, "detect: car")
• "[question]" - 回答关于图像的问题

示例:

// 图像描述
{
  "image_path": "photo.jpg",
  "prompt": "generate caption"
}

// 物体检测
{
  "image_path": "scene.jpg",
  "prompt": "detect: person"
}

// 视觉问答
{
  "image_path": "painting.jpg",
  "prompt": "What colors are used in this painting?"
}

🔧 技术细节

架构

该服务器作为一个双组件系统运行：

1. MCP 接口层

   • 处理协议通信
   • 管理工具接口
   • 处理请求/响应

2. Moondream 模型服务器

   • 运行视觉模型
   • 处理图像分析
   • 提供 HTTP API 端点

模型信息

使用 Moondream 量化模型：

• 默认: moondream-2b-int8.mf.gz
• 高效的 8 位量化
• 从 Hugging Face 自动下载
• ~500MB 模型大小

性能

• 通过自动缓存快速启动
• 通过量化实现高效的内存使用
• 响应迅速的 API 端点
• 并发请求处理

🔍 调试

常见问题和解决方案：

1. 模型下载问题

   # 手动模型下载
   wget https://huggingface.co/vikhyatk/moondream2/resolve/main/moondream-0_5b-int4.mf.gz
   

2. 服务器端口冲突

   • 默认端口: 3475
   • 检查进程使用情况: lsof -i :3475

3. Python 环境

   • UV 管理依赖项
   • 检查临时目录中的日志
   • 虚拟环境位于系统临时文件夹中

🤝 贡献

欢迎贡献！感兴趣的领域：

• 额外的模型支持
• 性能优化
• 新的分析能力
• 文档改进

📄 许可证

[在此处添加您的许可证信息]

🙏 鸣谢

• Moondream 模型团队
• 模型上下文协议 (MCP) 社区
• 贡献者和维护者

---

<p align="center"> 用 ❤️ 由 Nighttrek 制作 </p>