使用说明

语义图像搜索MCP服务器

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

特征

语义搜索：通过描述图像中的内容来查找图像，而不仅仅是文件名
零配置：无需手动标记-开箱即用
EXIF元数据：自动提取相机设置、日期和GPS数据
快速索引：针对Apple Silicon（MPS）和NVIDIA GPU（CUDA）进行了优化
克劳德集成：通过MCP与Claude Desktop原生协作
隐私优先：100%本地运行-您的照片永远不会离开您的机器
云同步库：索引“仅在线”文件（OneDrive files On Demand、iCloud Drive、Dropbox），而不将整个库保存在磁盘上——更改检测会读取占位符元数据，因此重新索引永远不会重新下载它已经知道的内容
增量和计划性重新索引：仅嵌入新的或更改的照片，并使用调度代理自动保持索引最新

快速开始

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

索引大型或云同步库

如果你的存档位于一个包含“仅限在线”文件的云文件夹中（OneDrive files On Demand、iCloud Drive“优化存储”、仅限Dropbox在线），你可以对整个库进行索引，而无需将其全部保存在磁盘上。

仅在线索引的工作原理。 索引器从占位符读取每个文件的大小和修改时间来检测新的或更改的文件没有下载文件。只有真正新的或改变的图像才会被物化和嵌入，因此重新索引一个不变的库不会下载任何东西。

文件夹驱动程序。 对于存储受限的机器上的大型库， index_library.py 索引一次允许列出文件夹，这样您就可以在文件夹之间释放空间：

# Index specific top-level folders (smallest first validates fast)
python3 index_library.py --config config.yml \
  --only "2019 Trip" --only "2020 Trip" --no-evict

# Or drive it from an allow-list file (one folder name per line)
cp folders.allow.example.txt folders.allow.txt   # then edit
python3 index_library.py --config config.yml --folders folders.allow.txt

--only NAME （可重复）或 --folders FILE：要索引哪些顶级文件夹
--max-gb N：在索引大于N GB的文件夹之前发出警告（默认值为50）
--no-evict：不提示在文件夹之间释放空间（用于无人值守运行）

在为文件夹建立索引后，其缩略图和嵌入内容将存储在本地，因此您可以安全地将原件仅返回在线（“释放空间”）并回收磁盘。只读取图像文件，因此同一树中的视频和其他大文件永远不会被下载。

精确的、无需训练的搜索索引。 FAISS指数使用 IndexFlatL2 （精确最近邻），适用于多达约20万张图像的库。它不需要训练步骤，可以在几毫秒内搜索数万张图像。

自动保持索引最新

reindex_missing.py 仅嵌入新的或更改的图像（使用上述大小/mtime检测），并重建搜索索引：

python3 reindex_missing.py

为了按计划运行它， auto_reindex.sh 将其与日志打包，捆绑的launchd代理将为您运行它。 com.himalayantrust.photo-reindex.plist 设置为每周运行-编辑其 StartCalendarInterval 对于不同的节奏：

cp com.himalayantrust.photo-reindex.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/com.himalayantrust.photo-reindex.plist

增量运行下载并嵌入新添加的照片，并将其保留在本地，直到您下次有空闲空间。对于较大的新容量（数十GB），请使用attended index_library.py 因此，驱逐可以控制峰值磁盘。

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

运作原理

索引:
- 扫描存档中的图像文件
- 提取EXIF元数据（相机、日期、位置等）
- 使用CLIP生成语义嵌入
- 将嵌入存储在FAISS向量索引中
- 将元数据保存在SQLite数据库中
搜索:
- 将文本查询转换为嵌入
- 在FAISS索引中搜索相似的图像嵌入
- 应用筛选器（日期、文件夹等）
- 返回具有相似性得分的排名结果
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服务器未连接

检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log
验证中的绝对路径 claude_desktop_config.json
确保 config.yml 存在于项目目录中
检查 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/

用例

博物馆和档案馆

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

非政府组织和实地工作

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

媒体公司

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

摄影师

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

研究人员

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

贡献

欢迎投稿！拜托：

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

许可证

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

致谢

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

支持

对于问题和疑问：

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

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

使用说明

语义图像搜索MCP服务器

特征

快速开始

1.安装

2.配置

3.为照片建立索引

4.设置Claude桌面集成

5.重新启动克劳德桌面

使用示例

搜索图片

获取图像详细信息

查看存档统计信息

添加照片后重新索引

索引大型或云同步库

自动保持索引最新

MCP工具

1. search_images

2. get_image_info

3. reindex_archive

4. get_archive_stats

配置参考

建筑

技术栈

运作原理

演出

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

搜索延迟

内存使用

故障排除

“未找到FAISS索引”错误

MCP服务器未连接

索引速度慢

导入错误

发展

运行测试

代码格式化

用例

博物馆和档案馆

非政府组织和实地工作

媒体公司

摄影师

研究人员

贡献

许可证

致谢

支持

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

Laravel文档聚合工具

1. `search_images`

2. `get_image_info`

3. `reindex_archive`

4. `get_archive_stats`