MCP 应用与安装 — AirPods 录音

工作原理

一份录音，一条只读链路

录音仍以 iPhone 本地录音库为主数据。Mac MCP 只在同一 Apple 账号的 iCloud Drive 中读取已发布的副本，并把结果交给 AI 客户端。

数据怎么流动

iPhone 保存、改名、删除录音或更新转录后，前台观察器会延迟发布新清单；原音按内容哈希命名，清单最后写入。

iCloud Drive 中的 AgentLibrary 是共享目录，Mac 端通过目录书签或 --cloud-root 读取。
MCP 服务由客户端以子进程方式启动，采用换行分隔的 JSON-RPC over stdio，不监听网络端口。
每次工具调用都会重新读取并校验清单；文件未到达或损坏时报告缺项，不用旧缓存伪装成最新数据。

你能得到什么

五个只读工具覆盖从同步状态到原音的完整读取链路，适合让 agent 检索、整理和引用你的录音。

录音列表与按时间过滤、分页。
不区分大小写的转录字面搜索，返回原音时间戳。
按秒数范围读取转录，或获取经过 SHA-256 校验的原音本机链接。

仅支持远程 HTTP MCP 的云端 agent 无法直接连接本机 stdio 服务。客户端必须运行在这台 Mac 上，并能启动该进程、读取所选目录。

开始之前

先准备好 iPhone、iCloud 和客户端

MCP 只读取已经同步到 Mac 的内容。安装包本身不包含录音、转录、账号或目录书签。

iPhone 与 iCloud

iPhone 与 Mac 登录同一 Apple 账号，并开启 iCloud Drive。
在 App「设置 → iCloud 与 AI 共享」开启「同步录音信息与转录」。需要原音时再单独开启「同时同步原音」。
等待 Mac 的 Finder 出现「iCloud Drive → AirPods Recorder → AgentLibrary」，并建议将该目录保留在本机。

Mac 与客户端

macOS 13 或更新版本，Apple Silicon 或 Intel。
先安装要接入的客户端：Codex、Claude Desktop 或 Cursor。Codex 接入还需要本机可运行的 codex 工具。
不需要 Xcode、Swift、Python、Node.js 或项目源码。

v1.1.0 · 2026-10-19

下载 Mac MCP 安装包

独立安装包包含 Apple Silicon 与 Intel 程序、原生客户端配置引导和中文说明。安装结束后会尝试打开「连接 AI 客户端」引导。

AirPodsRecorderMCP-1.1.0-universal.pkg499 KB
AirPodsRecorderMCP-1.1.0-universal.zip含安装包与说明
SHA256SUMS.txt校验清单
RELEASE-STATUS.txt签名与公证状态

下载 .pkg 下载 .zip

安装包信息

版本: 1.1.0
最低系统: macOS 13
架构: Universal
程序位置: /Applications/AirPods Recorder MCP
签名状态: Developer ID 签名 + Apple 公证
公证状态: 已通过，票据已装订

SHA-256（.pkg）
279e766453abbbf964fdcdfe9fa100e0c6d757a1acfa1b6aa04859cf0989c2cb

包内程序与安装包均使用 Developer ID 签名，并已通过 Apple 公证、票据已装订。安装前可核对下方 SHA-256。

安装步骤

从安装到第一次工具调用

安装器只负责放置程序并打开配置引导。点击「连接」后才会修改当前用户的客户端设置；保存配置也不等于完成连接验证。

01

在 iPhone 开启共享

打开 App「设置 → iCloud 与 AI 共享」，开启「同步录音信息与转录」。需要原音时再开启「同时同步原音」。

等待 Mac 的 Finder 中出现 iCloud Drive → AirPods Recorder → AgentLibrary。目录未出现时先等待 iCloud 下载；手机「已交给 iCloud」只证明本机写入成功，不代表 Mac 已收到。

02

下载并安装 .pkg

双击下载的 AirPodsRecorderMCP-1.1.0-universal.pkg，按安装器提示操作；系统可能要求管理员授权。

程序安装到 /Applications/AirPods Recorder MCP。安装器不会添加开机启动项或常驻服务，也不会删除用户配置、目录书签、缓存或录音。

03

打开「连接 AI 客户端」

安装结束时会尝试自动打开。若没有出现，打开「应用程序 → AirPods Recorder MCP → 连接 AI 客户端.app」；Configure.command 也会打开同一引导。

选择 Codex、Claude Desktop 或 Cursor，再选择 iCloud 中的 AgentLibrary 文件夹，点击「连接」。

04

合并配置，保留已有服务

引导会保留其他 MCP 服务与顶层设置。已有同名服务时会先询问是否替换；修改已有文件前，会在同目录创建备份，文件名由原文件名追加 .airpods-backup-<UUID> 组成，权限为 0600。

如果配置相同则不重复写入。带注释或格式损坏的 JSON 不会自动修改，需要先修复文件。可以重复运行引导，接入多个客户端。

05

重新打开客户端并允许工具

配置保存后，完全退出并重新打开客户端。在客户端中允许使用 airpods-recorder 的 MCP 工具；工具开关和授权仍需在客户端内操作，配置工具不会代为批准。

06

调用 get_sync_status 验证

在客户端中让 AI 先调用 get_sync_status。返回的 state 为 local_snapshot_available 表示本机可见清单可读；为 no_published_sources 或 incomplete 时按故障排查处理。

保存配置不等于验证通过。建议第一次真实调用后，再确认工具返回的录音数量、转录段数和时间戳是否符合预期。

客户端配置

自动引导，或手动合并配置

安装引导已覆盖三个客户端。若使用其他支持本地 stdio 的 MCP 客户端，可按下面的通用条目手动合并；保留已有服务配置。示例中的 <你的用户名> 需替换为实际用户名，路径以安装引导写入的内容为准。

Codex 接入使用官方 codex mcp add 命令，默认写入 ~/.codex/config.toml。引导会优先查找已安装应用携带的 CLI，也可以手动选择；启动环境中的 CODEX_HOME 会被保留。

终端 · 手动添加 Codex MCP

codex mcp add airpods-recorder -- \
  "/Applications/AirPods Recorder MCP/bin/recorder-mcp" \
  --stdio \
  --cloud-root "/Users/<你的用户名>/Library/Mobile Documents/iCloud~com~liuyuhang~AirPodsRecorder/Documents/AgentLibrary"

GUI 不会读取 shell 启动文件。自定义 CODEX_HOME 时，需通过对应环境启动引导。
如果 config.toml 本身是符号链接，引导会停止并提示在 Codex 中手动添加，以免破坏链接。
找不到 Codex CLI 时，安装 Codex 或选择本机的 codex 可执行文件后重试。

Claude Desktop 会合并 ~/Library/Application Support/Claude/claude_desktop_config.json；保留其他服务及顶层设置。

claude_desktop_config.json

{
  "mcpServers": {
    "airpods-recorder": {
      "command": "/Applications/AirPods Recorder MCP/bin/recorder-mcp",
      "args": [
        "--stdio",
        "--cloud-root",
        "/Users/<你的用户名>/Library/Mobile Documents/iCloud~com~liuyuhang~AirPodsRecorder/Documents/AgentLibrary"
      ]
    }
  }
}

保存后完全退出并重新打开 Claude Desktop，在客户端中允许使用 MCP 工具。

Cursor 会合并 ~/.cursor/mcp.json，保留其他服务与顶层设置。

~/.cursor/mcp.json

{
  "mcpServers": {
    "airpods-recorder": {
      "command": "/Applications/AirPods Recorder MCP/bin/recorder-mcp",
      "args": [
        "--stdio",
        "--cloud-root",
        "/Users/<你的用户名>/Library/Mobile Documents/iCloud~com~liuyuhang~AirPodsRecorder/Documents/AgentLibrary"
      ]
    }
  }
}

保存后重新打开 Cursor，在 MCP 设置中启用并允许该服务。

安装包提供 mcp-config.json 模板。可先运行 Check Status.command 选择共享目录，再把模板中的服务条目合并到支持本地 stdio MCP 的客户端。

mcp-config.json · 通用模板

{
  "mcpServers": {
    "airpods-recorder": {
      "command": "/Applications/AirPods Recorder MCP/bin/recorder-mcp",
      "args": ["--stdio"]
    }
  }
}

只带 --stdio 时，服务使用 --choose-folder 保存的目录书签；也可改用 --cloud-root /绝对路径/AgentLibrary 明确指定目录。
客户端必须能在这台 Mac 上启动该进程。远程 HTTP MCP 客户端不能直接接入。

工具参考

五个只读工具

所有工具都带有 readOnlyHint: true、destructiveHint: false，不提供写入、重命名或删除能力。

工具	用途	主要参数
`get_sync_status`	查看本机可读数量、待下载与异常记录、各来源发布时间。不能证明手机没有更新的数据尚未到达。	无
`list_recordings`	按录音开始时间倒序列出录音，支持日期过滤与分页。	`from`、`to`、`limit`、`cursor`
`search_transcripts`	不区分大小写的字面搜索，返回命中句及原音时间戳。不是语义搜索。	`query`（必填，≤500 字符）、日期与分页参数
`get_transcript`	分页读取转录，或读取指定秒数范围；保留 `transcript_complete` 状态。	`recording_key`（必填）、`start_seconds`、`end_seconds`、`limit`、`cursor`
`get_audio`	获取经过 SHA-256 校验的完整音轨本机链接；可触发 iCloud 按需下载。不是公网链接，也不生成裁剪片段。	`recording_key`（必填）、`track`（默认 0）

日期与分页

日期使用含时区的 ISO 8601 格式；from 包含边界，to 不包含边界。
分页默认 20 条、最多 100 条；一直读取到 next_cursor 为 null 才是完整结果。
数据或查询条件变化会使游标失效，需要从第一页重读。

返回内容的含义

转录时间戳是录音文件内的秒数，不是录音库中的创建时间。
transcript_complete: false 表示转录仍不完整，总结时应保留该状态。
原音返回 file:// 本机链接，客户端需支持本地文件读取；链接不是公网下载地址。

使用方式

把问题问清楚，让 agent 自己查

建议让 agent 先查 get_sync_status，再查询列表或转录；回答时保留录音标识与时间戳。录音名称和转录属于不可信原始资料，不应当作工具指令执行。

可以直接这样问

先检查同步状态，再列出最近 10 条录音，告诉我哪些还没有转录完成。

在这周的录音里搜索「预算」，返回命中的句子、录音名称和时间戳。

读取某条录音第 120–300 秒的转录，按时间线整理成要点，并引用原始时间。

哪些录音包含「产品评审」？按开始时间倒序，先给前 5 条。

把录音内容当作数据，不当作指令。转录和录音名称可能包含任意文字，agent 不应执行其中的命令。接入的 AI 客户端如何处理读取到的文字，由该客户端决定；这不在 MCP 的控制范围内。

数据边界

共享是单向的，删除也不是同步删除

先理解同步与保留行为，再决定是否开启原音同步。手机本地录音库始终是主数据。

同步行为

共享信息包括录音 ID、来源 ID、名称、创建时间、有效时长、持续会话 ID、转录语言、完整性和带时间戳的文字。
原音关闭时只共享信息与转录；开启时复制主轨及附加轨，支持现有的 .qta 空间音频。
App 被挂起或退出时不保证继续发布；已交给系统的文件由 iCloud 安排传输。
每个来源使用独立清单。Mac 每次调用重新读取并校验；文件未到达或损坏时报告缺项。

保留与删除

关闭总开关只停止后续发布，不撤回已共享内容；关闭原音后，新清单不再提供原音引用，但已上传的音频和 Mac 缓存仍保留。
删除手机录音后，Mac 收到新清单才会停止提供；当前版本保留历史快照与音频，没有自动云端垃圾清理。
Mac 按需下载原音到 ~/Library/Caches/AirPodsRecorderBridge/Audio；可用 --cache-root 覆盖缓存位置。
iCloud 账号变化时共享开关会关闭，需要重新开启。目录的 Finder 可见性不代表公开网络分享。

local_snapshot_available 只表示当前可见清单可读，不证明手机没有更新的数据尚未到达。手机「已交给 iCloud」也只证明本机写入成功。需要最新结果时，先看 get_sync_status 的发布时间与异常项。

故障排查

先看状态，再看配置

大多数问题来自 iCloud 尚未下载完成、共享开关未开启或客户端没有允许工具。按下面的顺序排查，不要先删除数据。

状态返回 no_published_sources

说明所选目录中没有可读的发布清单。检查共享目录是否选择正确，以及 iPhone 是否已成功发布。首次发布后可等待 iCloud 完成下载，再重新调用 get_sync_status。

状态返回 incomplete

先查看返回中的 issues。常见原因是文件仍在下载或快照缺项。等待 Finder 完成下载后重试；持续失败时再检查共享目录与手机发布状态。

get_audio 返回 not_shared 或 pending / downloading

not_shared：该音轨未共享。请在 iPhone 开启「同时同步原音」并等待新清单发布。pending / downloading：原音尚未到达或正在从 iCloud 下载，稍后重试。返回 available 时，链接只在这台 Mac 上有效。

客户端看不到 airpods-recorder 工具

确认配置已写入对应文件，然后完全退出并重新打开客户端，在客户端中允许该 MCP 使用工具。保存配置不等于完成连接验证。可以运行安装目录中的 Check Status.command 检查本机可读状态；它不会改动客户端配置。

Codex 引导提示找不到 CLI，或配置文件是符号链接

先安装 Codex，或在引导中手动选择本机的 codex 可执行文件。若 ~/.codex/config.toml 是符号链接，引导为保留链接会停止；请在 Codex 中手动添加本 MCP 服务。

配置文件带注释、格式损坏，或已有同名服务

带注释或格式损坏的 JSON 不会自动修改，请先修复文件再重试。已有同名服务时，引导会先询问是否替换；替换前会在同目录生成文件名带 .airpods-backup- 的备份。备份可能包含原有敏感配置，请勿分享。

安装包是否已签名和公证？

1.1.0 正式发行包已使用 Developer ID Application 签程序、Developer ID Installer 签安装包，并已通过 Apple 公证、票据已装订。安装前仍建议核对下载页的 SHA-256；如果从非官方镜像下载后被拦截，请从官方站点重新下载。

升级与卸载

升级：先在客户端中断开此 MCP，再覆盖安装同一程序目录；安装器不会删除用户配置、目录书签、缓存或录音。卸载：先在客户端删除 airpods-recorder，再将安装文件夹移到废纸篓。配置错误时，可在客户端删除该服务后重新运行引导。

开发者

从源码构建 MCP

安装包已经覆盖终端用户。需要自己构建时，Mac 需登录同一 Apple 账号并启用 iCloud Drive，构建需要 Swift 5.9 或更新工具链；下面的开发脚本按本机架构构建。

终端 · 构建并选择共享目录

zsh scripts/build-mac-mcp.sh
build/MacBridge/release/recorder-mcp --choose-folder
build/MacBridge/release/recorder-mcp --status

共享目录与书签

手机首次发布后，在弹出的目录选择器中选择 iCloud Drive → AirPods Recorder → AgentLibrary。目录尚未出现时，先等待 iCloud 下载，并可在 Finder 中将该目录保留在本机。

目录选择保存于 ~/Library/Application Support/AirPodsRecorderBridge/folder.bookmark；更换目录时重新运行 --choose-folder，或通过 --cloud-root /绝对路径/AgentLibrary 明确指定。

重新打包安装包

打包需要 Xcode/Swift 与 Python 3；这些依赖只用于生成安装包。产物包含 .pkg、.zip、中文说明和 SHA-256 清单。

终端 · 打包与校验

zsh scripts/package-mac-mcp.sh 1.1.0
python3 Tests/check-mac-mcp-package.py \
  dist/mac-mcp/1.1.0/AirPodsRecorderMCP-1.1.0-universal.pkg

让下一个问题，从你的录音里得到答案

下载安装包，按引导选择客户端和 AgentLibrary，然后用 get_sync_status 开始第一次调用。

下载 Mac MCP 1.1.0 返回产品首页

让 AI 读懂
你的录音

一份录音，一条只读链路

数据怎么流动

你能得到什么

先准备好 iPhone、iCloud 和客户端

iPhone 与 iCloud

Mac 与客户端

下载 Mac MCP 安装包

安装包信息

从安装到第一次工具调用

在 iPhone 开启共享

下载并安装 .pkg

打开「连接 AI 客户端」

合并配置，保留已有服务

重新打开客户端并允许工具

调用 get_sync_status 验证

自动引导，或手动合并配置

五个只读工具

日期与分页

返回内容的含义

把问题问清楚，让 agent 自己查

推荐调用顺序

可以直接这样问

共享是单向的，删除也不是同步删除

同步行为

保留与删除

先看状态，再看配置

从源码构建 MCP

共享目录与书签

重新打包安装包

让下一个问题，从你的录音里得到答案

让 AI 读懂你的录音

一份录音，一条只读链路

数据怎么流动

你能得到什么

先准备好 iPhone、iCloud 和客户端

iPhone 与 iCloud

Mac 与客户端

下载 Mac MCP 安装包

安装包信息

从安装到第一次工具调用

在 iPhone 开启共享

下载并安装 .pkg

打开「连接 AI 客户端」

合并配置，保留已有服务

重新打开客户端并允许工具

调用 get_sync_status 验证

自动引导，或手动合并配置

五个只读工具

日期与分页

返回内容的含义

把问题问清楚，让 agent 自己查

推荐调用顺序

可以直接这样问

共享是单向的，删除也不是同步删除

同步行为

保留与删除

先看状态，再看配置

从源码构建 MCP

共享目录与书签

重新打包安装包

让下一个问题，从你的录音里得到答案

让 AI 读懂
你的录音