AI导哈

照片库访问协议

一个基于Swift的模型上下文协议（MCP）服务器，通过Apple的PhotoKit框架为AI助手提供对macOS照片库的只读访问。

  • by maximbilan
  • Swift
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 maximbilan/photos-macos-mcp

使用说明

PhotosMCP

A. 模型上下文协议（MCP）服务器 Swift为AI助手提供了通过Apple的PhotoKit框架对macOS Photos库的只读访问权限。

需求

  • macOS 13.0+
  • Swift 6.0+（Xcode 16+）
  • 带有库的照片应用程序

建筑

swift build -c release

可执行文件将位于：

.build/release/PhotosMCP

Claude桌面应用程序集成

  1. 构建项目 （见上文）。

  2. 添加到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"

  1. 授予照片访问权限

    PhotosMCP进程（或父级Claude应用程序）需要访问您的照片库。如果系统提示，请允许它进入：

    系统设置→ 隐私和安全→ 照片

    如果服务器是由Claude桌面应用程序生成的，您可能需要授予照片访问Claude应用程序的权限。

  2. 重新启动克劳德 因此，它选择了新的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 系统temp文件夹中的子目录。新导出时，超过1小时的文件会自动删除。

项目结构

PhotosMCP/
├── Package.swift
├── Info.plist              # NSPhotoLibraryUsageDescription for Photos access
├── Sources/
│   └── PhotosMCP/
│       ├── main.swift              # Entry point, stdio transport
│       ├── PhotosServer.swift      # MCP server, tool registration
│       ├── Tools/
│       │   ├── ToolDefinitions.swift  # Tool schemas
│       │   ├── 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 structs
│           ├── ImageExport.swift      # PHImageManager, base64 JPEG
│           ├── PhotosAccess.swift     # Library authorization
│           ├── DateParsing.swift      # ISO 8601 date parsing
│           ├── GeoUtils.swift         # Haversine distance for location search
│           └── ContentClassifier.swift # Vision ML keyword matching
└── 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 对于范围。

许可证

麻省理工学院

相关 MCP