Photos Macos MCP

一个基于Swift开发的MCP服务器，为AI助手提供对macOS照片库的只读访问权限，通过PhotoKit框架实现照片浏览、搜索和元数据查询功能。

图像与视频处理知识管理与记忆 #照片管理 #macOS工具 #AI助手 #只读访问 .swift

评分 : 2.5分

下载量 : 4.8K

更新时间 : 2026-03-13

打开站点

什么是PhotosMCP?

PhotosMCP是一个连接AI助手（如Claude）与您macOS照片库的桥梁。它允许AI助手以只读方式访问您的照片和视频，帮助您通过自然语言搜索和整理回忆。例如，您可以问'帮我找去年在巴黎拍的照片'或'显示所有海滩相关的照片'。

如何使用PhotosMCP?

只需在Claude Desktop中配置一次，之后就可以像与朋友聊天一样询问您的照片库。AI助手可以帮您按地点、日期、内容或相册查找照片，甚至生成照片描述和回忆总结。

适用场景

• 快速查找特定时间或地点的照片 • 整理旅行照片并生成回忆录 • 寻找特定主题的照片（如食物、宠物、风景） • 统计照片库信息（照片数量、时间范围等） • 浏览和管理相册

主要功能

智能照片搜索

支持按日期、地点、内容关键词（如'海滩'、'食物'、'城市'）搜索照片，使用AI技术识别照片内容

地理位置查找

通过地名（如'巴黎'、'东京'）或经纬度查找照片，自动将地名转换为坐标并搜索附近拍摄的照片

相册管理

浏览所有相册（包括智能相册），查看相册内容和统计信息

照片预览

获取照片缩略图或完整图像，支持base64格式输出，方便AI助手查看照片内容

库统计信息

获取照片库的整体统计：照片数量、视频数量、时间范围、相册数量等

安全只读访问

仅提供读取权限，不会修改、删除或创建任何照片或相册，确保数据安全

优势

自然语言交互：用聊天的方式查找照片，无需手动浏览

智能识别：AI自动识别照片内容（食物、风景、宠物等）

隐私保护：仅在本地运行，照片数据不会上传到云端

易于使用：一次配置，永久使用，无需重复操作

跨相册搜索：同时搜索所有相册，打破相册边界

局限性

仅限macOS：需要macOS 13.0或更高版本

需要照片访问权限：首次使用需授权访问照片库

只读功能：无法编辑、删除或整理照片

关键词识别有限：内容识别基于预训练模型，可能无法识别所有内容

地理位置搜索依赖网络：地名转坐标需要网络连接

如何使用

安装与构建

确保您已安装Xcode 16+和Swift 6.0+，然后构建项目

配置Claude Desktop

在Claude Desktop配置文件中添加PhotosMCP服务器路径

添加配置

在配置文件中添加以下内容（替换为您的实际路径）

授权照片访问

首次使用时，系统会提示授权照片访问权限。前往系统设置→隐私与安全→照片，确保Claude应用有访问权限

重启并开始使用

重启Claude Desktop，然后就可以开始用自然语言查询照片了

使用案例

旅行回忆整理

您刚从日本旅行回来，想整理旅行照片并生成旅行总结

寻找特定照片

您记得拍过一张美味的披萨照片，但忘记放在哪个相册了

家庭照片整理

您想整理孩子的成长照片，按年份和地点分类

照片库分析

您想了解自己的拍照习惯和照片库状况

常见问题

PhotosMCP会修改或删除我的照片吗？

我的照片数据会上传到云端吗？

为什么有些照片无法通过关键词找到？

支持搜索视频吗？

需要一直保持网络连接吗？

如何撤销照片访问权限？

支持iCloud照片库吗？

搜索速度如何？

🚀 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 参数指定日期范围。