金大哥 - photos-macos-mcp MCP 详情

article

README

🚀 PhotosMCP

PhotosMCP 是一个用 Swift 编写的 模型上下文协议（MCP）服务器，它借助苹果的 PhotoKit 框架，为 AI 助手提供对 macOS 照片库的只读访问权限。

🚀 快速开始

环境要求

macOS 13.0 及以上版本
Swift 6.0 及以上版本（Xcode 16 及以上）
安装有照片库的照片应用程序

构建项目

在终端中执行以下命令来构建项目：

swift build -c release

构建完成后，可执行文件将位于以下路径：

.build/release/PhotosMCP

与 Claude 桌面应用集成

构建项目：按照上述步骤构建项目。

添加到 Claude 桌面应用配置：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 文件，添加如下内容：

{
  "mcpServers": {
    "photos": {
      "command": "/Users/YOUR_USERNAME/Developer/photos-macos-mcp/.build/release/PhotosMCP",
      "args": []
    }
  }
}

将 YOUR_USERNAME（或整个路径）替换为你实际构建的二进制文件的绝对路径，例如：

"command": "/Users/max/Developer/photos-macos-mcp/.build/release/PhotosMCP"

授予照片访问权限： PhotosMCP 进程（或其父级 Claude 应用）需要访问你的照片库。如果系统提示，请在 系统设置 → 隐私与安全 → 照片 中授予访问权限。如果服务器是由 Claude 桌面应用启动的，你可能需要授予 Claude 应用访问照片的权限。
重启 Claude：重启 Claude 桌面应用，使其加载新的 MCP 服务器。

✨ 主要特性

MCP 工具

| 工具 | 描述 | |------|-------------| | list_albums | 列出所有用户相册和智能相册（包括名称、ID、资产数量、类型） | | get_library_stats | 获取照片库的统计信息，如照片总数、视频总数、相册总数和日期范围 | | search_photos | 根据日期范围、媒体类型、收藏状态、关键字进行照片搜索 | | get_album_contents | 根据相册标识符获取相册中的资产 | | get_asset_details | 获取资产的完整元数据 | | get_photo_thumbnail | 获取照片的 Base64 编码 JPEG 缩略图 | | get_photo_full | 获取照片的全分辨率 Base64 编码 JPEG 图像 | | get_photos_by_place | 根据地点名称（如瓦伦西亚、巴黎）搜索照片，会进行地理编码和搜索操作 | | get_photos_by_location | 根据经纬度半径搜索照片 | | get_photos_by_date | 根据日期或日期范围搜索照片 | | list_moments | 列出时刻/集合（在 macOS 上仅适用于 iOS 相关功能） |

所有列表/搜索工具都支持 limit（默认值为 50，最大值为 200）和 offset 参数，用于分页操作。

权限管理

服务器使用 PHPhotoLibrary.requestAuthorization 方法，首次使用时会显示系统对话框。如果访问被拒绝，工具会返回明确的错误消息。

只读访问

该服务器仅提供只读访问权限，不会修改、删除或创建资产或相册。

隐私与数据处理

地点搜索（get_photos_by_place）：你提供的地点名称（如“瓦伦西亚”、“巴黎”）会被发送到苹果的地理编码服务以解析坐标，这可能涉及网络请求。
图像导出：缩略图和全分辨率图像会被写入系统临时文件夹的 PhotosMCP 子目录中。新导出图像时，超过 1 小时的文件会被自动删除。

🔧 技术细节

项目结构

PhotosMCP/
├── Package.swift
├── Info.plist              # 用于照片访问的 NSPhotoLibraryUsageDescription
├── Sources/
│   └── PhotosMCP/
│       ├── main.swift              # 入口点，标准输入输出传输
│       ├── PhotosServer.swift      # MCP 服务器，工具注册
│       ├── Tools/
│       │   ├── ToolDefinitions.swift  # 工具模式定义
│       │   ├── LibraryTools.swift    # list_albums、get_library_stats、list_moments 工具实现
│       │   ├── SearchTools.swift     # search_photos、get_photos_by_location、get_photos_by_date 工具实现
│       │   ├── AlbumTools.swift      # get_album_contents 工具实现
│       │   ├── AssetTools.swift      # get_asset_details 工具实现
│       │   └── ImageTools.swift      # get_photo_thumbnail、get_photo_full 工具实现
│       └── Helpers/
│           ├── PhotoKitHelpers.swift  # PHAsset 转换为 JSON 结构体
│           ├── ImageExport.swift      # PHImageManager，Base64 JPEG 处理
│           ├── PhotosAccess.swift     # 照片库授权
│           ├── DateParsing.swift      # ISO 8601 日期解析
│           ├── GeoUtils.swift         # 用于位置搜索的 Haversine 距离计算
│           └── ContentClassifier.swift # Vision ML 关键字匹配
└── README.md

注意事项

list_moments 在 macOS 上返回空列表，因为 fetchMoments API 仅适用于 iOS。
search_photos 中的 关键字搜索 使用 Vision ML 技术（支持搜索如披萨、食物、汽车、城市、狗、海滩等关键字），最多分析 1000 张照片，对于大型照片库，建议结合日期范围进行搜索。
地点搜索（get_photos_by_place）会对“瓦伦西亚”、“巴黎”等地点名称进行地理编码，并查找在这些地点拍摄的照片。
日期搜索 支持 yyyy-MM-dd 格式或完整的 ISO 8601 格式，使用 start_date 和 end_date 参数指定日期范围。

📄 许可证

本项目采用 MIT 许可证。

photos-macos-mcp