Apple Maps

@mgcrea/mcp-apple-maps

适用于 macOS 地图应用的 MCP 服务：你保存的地点。

{
  "mcpServers": {
    "apple-maps": { "command": "npx", "args": ["-y", "@mgcrea/mcp-apple-maps"] }
  }
}

可读取的内容

从地图的 Core Data 存储中读取收藏、合集（指南）和最近浏览记录，包含名称、地址和真实坐标。

工具	内容
apple_maps_list_favorites	已保存为收藏的地点
apple_maps_list_collections	指南
apple_maps_list_collection_places	某个指南中归档的内容
apple_maps_list_unfiled_places	已保存但未归档到任何指南的地点
apple_maps_list_recents	最近浏览过的地点
apple_maps_search_places	按名称、标签或地址一次搜索以上三类内容
apple_maps_get_place	按引用获取一个地点
apple_maps_diagnostics	检查已打开的内容、解析出的列以及无法执行的操作

可写入的内容

仅当设置了 APPLE_MAPS_ALLOW_WRITES=1 时可用。关闭时，这两个工具不会注册，而不是拒绝请求，因此未选择启用写入的客户端根本不会知道它们的存在。

工具	内容
apple_maps_add_favorite	将地点保存为收藏，通过 maps:// 创建记录
apple_maps_remove_favorite	删除一条收藏记录

还有三个工具通过辅助功能操作地点卡片上的按钮，而非写入 SQL；仅当 Cupertino.app 托管此 MCP 服务时才会注册：授权属于应用，因此通过 npm 运行的包无法使用这些工具，也不会知道它们的存在。

工具	内容
apple_maps_save_place	将地点添加到地点库（与置顶不同）
apple_maps_remove_saved_place	从地点库中移除地点
apple_maps_add_place_to_guide	将地点归档到现有指南中；地图无法确认是否成功

每项操作都会打开地图、将其窗口置于前台，并在最近浏览记录中留下该地点。

不会执行的操作

它读取的是这台 Mac 上保存的内容。它不会搜索 Apple 的全球地图、对地址进行地理编码、提供路线指引或计算出行时间。这些操作需要调用 Apple 的服务，而非读取磁盘上的数据。

仅当设置了 APPLE_MAPS_ALLOW_WRITES 时，它才会写入内容：通过存储写入收藏，通过地图自身的界面操作地点库和指南成员关系。除此之外的所有操作均为只读。存储由 NSPersistentCloudKitContainer 镜像到 iCloud，因此写入意味着在正在运行的应用下编辑同步对象图中的一个副本；格式错误的记录会传播到该账户下的所有设备。因此绝不会伪造地点记录：添加收藏时会打开 maps://，让地图自行创建记录，然后才复制该记录。无论你是否保留收藏，该地点都会留在最近浏览记录中，而通过网络解析地点可能需要几十秒。

必须启用完全磁盘访问权限

这不是可选的优化。地图没有提供脚本字典，因此没有可替代的 Apple Events 通道——未授予权限时，此 MCP 服务会返回错误，绝不会返回空列表。请将权限授予运行此 MCP 服务的应用，而不是地图。

如果列表为空，说明你没有保存此类内容。运行 apple_maps_diagnostics 即可区分这两种情况。

配置

变量	默认值	说明
APPLE_MAPS_STORE	discovered	显式指定存储路径，用于测试和取证副本
APPLE_MAPS_INDEX_MODE	auto	auto / ro / immutable / off
APPLE_MAPS_MAX_RESULTS	50	默认结果上限
APPLE_MAPS_SEED_TIMEOUT_MS	30000	add_favorite 等待 Maps 解析地点的时长
APPLE_MAPS_EXPOSE_PROMPTS	on	注册提示词和 cupertino://maps/* 资源
APPLE_MAPS_DEBUG	off	在 stderr 上输出详细日志

APPLE_MAPS_ALLOW_WRITES（off）会注册写入内容中列出的工具。

请参阅 docs/maps.md，了解阶段 0 的测量结果，其中包括该存储有三次被宣称不存在的情况。

许可协议

MIT。