Semantic Image Search MCP

语义图像搜索MCP服务器

使用具有人工智能语义理解的自然语言搜索您的照片档案。作为MCP（模型上下文协议）服务器构建，可与Claude Desktop无缝集成。

特性

• 语义搜索：通过描述图像中的内容来查找图像，而不仅仅是文件名
• 零配置：无需手动标记-开箱即用
• EXIF元数据：自动提取相机设置、日期和GPS数据
• 快速索引：针对Apple Silicon（MPS）和NVIDIA GPU（CUDA）进行了优化
• 克劳德集成：通过MCP与Claude Desktop原生协作
• 隐私第一：100%本地运行-您的照片永远不会离开您的机器

快速开始

1.安装

# Clone the repository
git clone https://github.com/himalayantrust/semantic-image-search-mcp
cd semantic-image-search-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.配置

# Copy example configuration
cp config.yml.example config.yml

# Edit config.yml with your photo archive path
nano config.yml  # or use your preferred editor

最低配置：

archive_path: "/path/to/your/photos"

3.为照片建立索引

# Run initial indexing
python3 -c "
import asyncio
from pathlib import Path
from src.config import Config
from src.indexer import ImageIndexer

async def index():
    config = Config.from_yaml(Path('config.yml'))
    indexer = ImageIndexer(config)
    stats = await indexer.index_archive()
    print(f'Indexed {stats[\"indexed\"]} images')

asyncio.run(index())
"

4.设置Claude桌面集成

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "semantic-image-search": {
      "command": "python3",
      "args": ["/absolute/path/to/photo-library/run_server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/photo-library"
      }
    }
  }
}

5.重新启动克劳德桌面

更新配置后，重新启动Claude Desktop。你应该看看 semantic-image-search 服务器连接到MCP部分。

使用示例

搜索图片

问克劳德：

Search my photos for images with people in classrooms

Find photos of mountain landscapes taken in 2024

Show me portraits with natural lighting

获取图像详细信息

Get detailed information about image abc123def456

查看存档统计信息

Show me statistics about my photo archive

添加照片后重新索引

Reindex my photo archive

MCP工具

服务器向Claude公开了四个工具：

1. search_images

使用带有可选过滤器的自然语言查询搜索图像。

参数：

• query （字符串，必填）：自然语言描述
• limit （整数，可选）：最大结果（默认值：10，最大值：100）
• date_from （字符串，可选）：按日期筛选（ISO格式：YYYY-MM-DD）
• date_to （字符串，可选）：按日期筛选（ISO格式：YYYY-MM-DD）
• folder_pattern （字符串，可选）：按文件夹路径筛选

例子：

{
  "query": "person standing in a room",
  "limit": 5,
  "date_from": "2024-01-01"
}

2. get_image_info

获取特定图像的详细元数据。

参数：

• image_id （字符串，必填）：唯一图像标识符

3. reindex_archive

为新的或修改过的图像重新索引照片存档。

参数：

• force （布尔值，可选）：强制重新索引所有图像（默认值：false）

4. get_archive_stats

获取有关索引照片存档的统计信息。

无需参数。

配置参考

# Path to your photo archive (required)
archive_path: "/path/to/photos"

# Directory for storing index data (optional)
data_dir: "./data"

# CLIP model configuration
clip:
  # Model to use for embeddings
  model_name: "openai/clip-vit-base-patch32"  # or "openai/clip-vit-large-patch14"

  # Device for inference
  device: "auto"  # auto, mps, cuda, or cpu

  # Batch size for processing
  batch_size: 32  # Increase for more RAM/VRAM

# Search configuration
search:
  default_limit: 10
  max_limit: 100
  similarity_threshold: 0.0  # 0.0 = show all ranked results

# Thumbnail configuration
thumbnails:
  enabled: true
  max_size: 512
  quality: 85

建筑

技术栈

• CLIPOpenAI用于理解图像的视觉语言模型
• FAISS：Facebook的向量相似性搜索库
• SQLite：用于元数据存储的轻量级数据库
• 主控程序：用于Claude集成的模型上下文协议
• PyTorch：支持Apple Silicon（MPS）的ML框架

运作原理

1. 索引:

- 扫描存档中的图像文件 - 提取EXIF元数据（相机、日期、位置等） - 使用CLIP生成语义嵌入 - 将嵌入存储在FAISS向量索引中 - 将元数据保存在SQLite数据库中

1. 搜索:

- 将文本查询转换为嵌入 - 在FAISS索引中搜索相似的图像嵌入 - 应用筛选器（日期、文件夹等） - 返回具有相似性得分的排名结果

1. MCP集成:

- 通过stdio协议向Claude公开搜索工具 - Claude可以搜索、获取详细信息并管理您的档案 - 所有处理都在您的机器上本地进行

演出

索引速度（苹果Silicon M系列）

• 小型档案 （\<1000张图片）：约30秒
• 中型档案 （1000-10000张图片）：2-5分钟
• 大型档案 （10000多张图片）：10-30分钟

搜索延迟

• 典型查询：200-500毫秒
• 带过滤器：300-700ms

内存使用

• 基础：~200MB（型号+服务器）
• 每10000张图片：~20MB（嵌入+元数据）

故障排除

“未找到FAISS索引”错误

先运行索引：

python3 -c "import asyncio; from src.indexer import ImageIndexer; from src.config import Config; from pathlib import Path; asyncio.run(ImageIndexer(Config.from_yaml(Path('config.yml'))).index_archive())"

MCP服务器未连接

1. 检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log
2. 验证中的绝对路径 claude_desktop_config.json
3. 确保 config.yml 存在于项目目录中
4. 检查 mcp-server.log 对于错误

索引速度慢

• 减少 batch_size 在config.yml中（使用更少的内存，速度稍慢）
• 检查是否正在使用MPS/CUDA（查找“使用苹果硅MPS”消息）
• 关闭其他应用程序以释放RAM

导入错误

确保虚拟环境已激活：

source venv/bin/activate  # On Windows: venv\Scripts\activate

发展

运行测试

pytest tests/

代码格式化

black src/
ruff check src/

用例

博物馆和档案馆

按内容、时代或主题搜索历史照片集。

非政府组织和实地工作

查找来自特定旅行、地点或活动的照片，以供报道和社交媒体使用。

媒体公司

快速找到与创意内裤相匹配的库存镜头和图像。

摄影师

按视觉内容组织和搜索大型作品集。

研究人员

在大型数据集中查找特定图像以供分析和发布。

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 建立在 CLIP 通过OpenAI
• 用途 FAISS Meta AI研究
• 实现 模型上下文协议 通过Anthropic

支持

对于问题和疑问：

• GitHub问题：https://github.com/himalayantrust/semantic-image-search-mcp/issues
• 电子邮件：info@himalayantrust.org

______________________________________________________________________

喜马拉雅信托团队用爱建造 🏔️