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. 构建项目 （见上文）。

1. 添加到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应用程序的权限。

1. 重新启动克劳德 因此，它选择了新的MCP服务器。

MCP工具

所有列表/搜索工具支持 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 对于范围。

许可证

麻省理工学院