IMCP

iMCP 是一款 macOS 应用，可将你的数字生活与 AI 连接起来。 它支持 Claude Desktop、 ChatGPT 桌面应用、 由 llama.cpp 提供服务的本地模型， 以及越来越多支持 模型上下文协议（MCP） 的客户端。

功能

	日历	查看和管理日历事件，包括创建新事件，并自定义重复规则、提醒和空闲状态等设置。
	联系人	访问关于您本人的联系信息，并按姓名、电话号码或电子邮件地址搜索联系人。
	家庭	查找家庭、房间、配件、场景和自动化，读取和控制配件，并整理房间和区域。需要使用您自己的 Apple Developer 账户构建辅助应用。
	位置	访问当前位置数据，并在地址和地理坐标之间进行转换。
	邮件	列出邮箱，按发件人、主题、邮箱、日期或已读状态搜索邮件，读取存储在 Mac 上的邮件，并在默认电子邮件应用中打开新草稿。读取邮件需要访问您的 Mail 文件夹。
	地图	提供位置服务，包括地点搜索、路线查询、兴趣点查询、出行时间估算和静态地图图像生成。
	信息	在自定义日期范围内访问与特定参与者的消息记录。
	音乐	查看音乐应用中正在播放的内容、控制播放，并搜索 Apple Music 目录。播放工具需要获得音乐的自动化权限；目录搜索需要访问 Apple Music。
	备忘录	按文本、文件夹或日期搜索备忘录，并以 Markdown 格式读取，其中包括清单、表格和链接。
	电话	查看从 iPhone 同步的通话记录，按参与者、日期或通话类型筛选通话，并在系统确认后发起通话。
	提醒事项	查看、创建、编辑和删除提醒事项，并可自定义到期日期、重复规则、优先级和提醒，还可管理不同提醒事项列表及列表本身。
	快捷指令	列出并运行 Mac 上的快捷指令，也可选择输入文本。
	语音备忘录	获取语音备忘录中的录音及其转录文本和音频，可按标题、文件夹或日期筛选，也可读取“最近删除”中的内容。需要访问您的语音备忘录文件夹。
	语音留言	获取从 iPhone 同步的语音留言及其转录文本和音频，可按发件人、日期、留言类型或邮箱（收件箱、已阻止或已删除）筛选。
	天气	访问任意位置的当前天气状况，包括温度、风速和天气情况。

要使用 iMCP，你需要两个应用： iMCP，用于访问你启用的服务， 以及一个能够连接 MCP 服务的 AI 应用。 请先安装 iMCP 并启用服务。 然后按照 AI 应用的说明操作：

• Claude Desktop
• ChatGPT 桌面应用
• Claude Code、llama.cpp 和其他客户端

下载并打开应用

首先，下载 iMCP 应用 （需要 macOS 15.3 或更高版本）。

或者，如果你已安装 Homebrew， 可以运行以下命令：

brew install --cask mattt/tap/iMCP

打开应用后， 你会在菜单栏中看到一个 图标。

点击此图标即可打开 iMCP 菜单。 顶部的蓝色“Enable MCP Server”开关表示 MCP 服务正在运行，可以连接 AI 应用。 iMCP 必须保持打开，AI 应用才能使用它。

开关下方的菜单列出了可用服务。 首次打开 iMCP 时，地图服务处于开启状态； 其他服务处于关闭状态，并显示为灰色。 iMCP 还包含一个用于播放系统声音的工具。 即使所有服务都关闭，该工具也始终可用， 因此你可以在不授予任何权限的情况下测试连接。

启用服务

要启用某项服务，请点击其图标。 macOS 会请求你的许可。 例如，启用日历时， 系统会显示对话框“‘iMCP’想要获得对日历的完全访问权限”。 点击“允许完全访问”以继续。

重要

iMCP 不会收集或存储你的任何数据。 Claude 和 ChatGPT 等 AI 应用会在调用工具时 将你的数据发送到设备之外。 仅启用你希望 AI 应用使用的服务。 若要将数据保留在 Mac 上， 请使用 llama.cpp 本地模型。

服务开启后， 其图标会从灰色变为对应服务的颜色： 日历为红色，信息为绿色，位置为蓝色，依此类推。

对要使用的每项服务重复这些步骤。 macOS 会分别请求每项权限， 因此 iMCP 只能访问你允许的数据。 要关闭某项服务，请再次点击其图标。 要关闭某项服务中的单个工具， 请点击 >“设置”，然后点击侧边栏中的该服务。

批准连接

AI 应用首次连接时， iMCP 会显示“客户端连接请求”对话框， 其中包含应用报告的名称 以及该应用可以使用的服务。 点击“允许”即可连接。 若要下次跳过此对话框，请选择“始终信任此客户端”； 之后每次应用连接时，iMCP 都会显示通知。 你可以在 >“设置”>“客户端”中移除受信任的客户端。

邮件存储访问使用 Envelope， 它会读取本地索引和邮件文件， 并通过其内部 MIME 读取器选取可读内容。 iMCP 管理文件夹访问、工具参数、JSON 输出和撰写邮件。

读取邮件需要访问 ~/Library/Mail。 如果无法访问文件夹，mail_compose 仍可在默认邮件应用中打开撰写窗口。 它不会保存或发送邮件。

读取邮件使用只读 SQLite 连接，并要求使用 WAL 日志模式。 iMCP 不会更改索引的日志模式，也不会运行检查点。 它一次只允许一个邮件数据库连接； 并发读取会依次等待， 如果 SQLite 报告锁冲突，读取将返回错误。 每条 SQL 语句的执行时限为 100 ms， 同一次读取中的所有语句共用 1 s 时限， 且语句会检查任务是否已取消。 此时限采用协作式机制；SQLite 等待文件系统操作完成时，它无法中断该操作。 搜索较慢时可能会失败，而不是返回结果。 服务状态检查不会打开 SQLite 连接， 读取邮件时，会在扫描邮箱文件前关闭数据库。 这些限制可减少干扰，但正在进行的读取仍可能延迟 WAL 检查点。

在 mail_messages_search 中，将 mail_mailboxes_list 返回的 @id 字符串用作 mailbox 筛选条件， 例如 {"mailbox": "V10:12"}。 该标识符包含邮件存储的信息， 因此，邮件存储升级前的标识符会导致错误。 url 字段描述存储位置，不是搜索标识符。 每个邮箱都会在可用时包含账户标识符。 账户的 email 字段来自 Mail 的本地账户映射； 如果该映射缺失或不包含电子邮件地址，则值为 null。

搜索结果包含所选邮箱的 localIndex.indexedMessageCount； 若未选择邮箱，则包含所有邮箱的计数，且计数是在筛选和分页之前计算的。 此计数会计算标签归属，但不会重复计算同一封邮件。 同步状态报告为 unknown。 计数为零可能表示邮箱为空，也可能表示本地未建立索引； 无法据此判断 Mail 是否曾为该账户建立索引。 请打开 Mail 检查账户同步情况。

搜索结果按时间从新到旧排列。 如果匹配的邮件较多，结果会包含 nextCursor 值； 使用相同的筛选条件，将其作为 cursor 传入即可获取下一页。 游标指向某一页的最后一封邮件， 因此，两次请求之间收到的新邮件不会改变后续页面的内容。

搜索仅匹配发件人和主题元数据。 mail_messages_read 可读取返回邮件的本地内容。 它会列出附件，但不包含附件内容。 如果 Mail 将邮件附件或内嵌图像存储在单独的文件中， 邮件文件中会保留文本，且这些附件的 isStoredSeparately 均设为 true。 这些工具不支持搜索邮件正文，也不会下载邮件。

连接到 Claude Desktop

如果尚未安装 Claude Desktop， 可以在此处下载。

打开 Claude Desktop，选择 Claude >“设置”（⌘,）。 在侧边栏中点击“开发者”， 然后点击“编辑配置”。 这会在以下位置创建配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json。

要将 iMCP 连接到 Claude Desktop， 点击 >“配置 Claude Desktop”， 然后点击“设置”。

iMCP 会在配置文件中添加或更新其条目， 以便 Claude Desktop 在应用中启动 imcp-server 可执行文件。 iMCP 会保留文件中的其他 MCP 服务。

{
  "mcpServers": {
    "iMCP": {
      "command": "{paste iMCP server command}"
    }
  }
}

退出并重新打开 Claude Desktop 应用。 iMCP 会要求你批准连接。

批准连接后， 聊天框右下角会出现一个 🔨 图标， 旁边显示可用工具的数量。 点击该图标，即可查看 Claude 可以使用的 iMCP 工具。

现在，你可以向 Claude 提出需要访问个人数据的问题， 例如：

“我所在位置的天气怎么样？”

Claude 会使用 iMCP 工具获取这些信息， 因此你无需在对话中自行分享。

连接到 ChatGPT 桌面应用

如果尚未安装 ChatGPT 桌面应用， 可以在此处下载。

说明

以下步骤使用的是 macOS 版 ChatGPT 26.930 中的标签， 目前尚未经过端到端测试。 OpenAI 为 Codex 模式 提供了 MCP 服务文档，因此请在 Codex 对话中使用 iMCP。

1. 点击 >“将服务命令复制到剪贴板”。
2. 在 ChatGPT 中打开“设置”（⌘,）， 然后点击侧边栏中的“MCP 服务”。
3. 点击“添加服务”。 在“名称”中输入 iMCP，在“类型”中选择“STDIO”， 并将复制的命令粘贴到“启动命令”中。 其他字段留空。
4. 点击“保存”，然后点击“重新启动”。
5. 在 iMCP 中批准连接。 ChatGPT 可能会将自身标识为 codex-mcp-client。

要测试连接， 请开始新的 Codex 对话，并发送以下消息：

“使用 iMCP 播放系统提示音。”

你的 Mac 会播放一段短音效。 如果 Mac 已静音，请打开对话中的工具调用； 结果为 true 表示 iMCP 已收到请求。

大多数 MCP 客户端都可以将 iMCP 作为使用 STDIO 传输的本地服务启动。 点击 >“将服务命令复制到剪贴板”， 然后在客户端中新建 STDIO 服务，并将复制的命令填入命令栏。 复制的命令是你安装的 iMCP 中 imcp-server 可执行文件的完整路径。

以下命令假定 iMCP 安装在 Applications 文件夹中。 如果你将 iMCP 安装在其他位置， 请将 /Applications/iMCP.app/Contents/MacOS/imcp-server 替换为复制的命令。

Claude Code

如需为所有项目添加 iMCP，请运行以下命令：

claude mcp add --scope user iMCP -- /Applications/iMCP.app/Contents/MacOS/imcp-server

claude mcp add-from-claude-desktop

llama.cpp

你可以通过 llama.cpp，在 Mac 上使用 iMCP 和本地运行的开源模型， 让对话和工具结果保留在 Mac 上。 llama-server（或 llama serve）会启动配置文件中列出的 MCP 服务， 并在其 Web UI 中向模型提供这些服务的工具。 这要求 llama.cpp 版本为 0.1.0 或更高版本。

创建文件 ~/.config/llama/mcp.json，并写入以下内容：

{
  "mcpServers": {
    "imcp": {
      "command": "/Applications/iMCP.app/Contents/MacOS/imcp-server"
    }
  }
}

然后使用 --mcp-servers-config 选项和支持工具调用的模型启动服务：

llama serve --mcp-servers-config ~/.config/llama/mcp.json \
            -hf ggml-org/Qwen3-4B-GGUF

在 http://localhost:9931 打开 Web UI （0.7.0 之前的 llama.cpp 版本使用端口 8080）。 iMCP 工具会显示为带有 imcp_ 前缀的名称， 例如 imcp_weather_current。 Web UI 会在每次运行工具调用前征求你的许可， 除非你选择始终允许该工具。

defaults write app.llama.Llama extraServerArgs -string "--mcp-servers-config $HOME/.config/llama/mcp.json"

重要

服务启动时， 会等待 10 秒，让 iMCP 列出其工具。 如果你未在这段时间内批准来自“llama.cpp”的连接， 在重启服务之前都不会显示 iMCP 工具。

技术详情

应用与 CLI

iMCP 是一款 macOS 应用，内置命令行可执行文件 imcp-server。

• iMCP.app 提供用于配置服务的 UI，并且最重要的是， 可与 macOS 系统权限交互， 从而访问通讯录、日历及其他信息。
• imcp-server 提供一个 MCP 服务，通过标准输入/输出进行通信 （stdio 传输）。

应用与 CLI 使用 Bonjour 在本地网络上自动发现彼此并进行通信。 二者都会发布类型为“_mcp._tcp”、域名为“local”的服务。 MCP 客户端的请求由 CLI 从 stdin 读取并转发给应用； CLI 接收应用的响应后，将其写入 stdout。 实现详情请参阅 StdioProxy。

在这个项目中，我们创建了后来成为 Model Context Protocol 服务和客户端的 官方 Swift SDK。 应用使用此程序包处理来自 MCP 客户端的代理请求。

iMessage 数据库访问

Apple 不提供访问你消息的公共 API。 不过，macOS 上的“信息”应用会将数据存储在 ~/Library/Messages/chat.db 这个 SQLite 数据库中。

iMCP 在 App Sandbox 中运行， 这会限制它访问用户数据和系统资源。 启用“信息”服务时， 系统会提示你通过标准文件选择器选择 ~/Library/Messages 文件夹。 选择后，macOS 会将该文件夹添加到应用的沙盒中。 NSOpenPanel 就是这么神奇。 文件夹很重要：chat.db 是一个 WAL 模式数据库， “信息”会先将每条新消息写入旁边的 chat.db-wal， 只有在每隔几 MB 执行一次检查点时，才会将日志合并到 chat.db 中—— 通常要等上好几个小时。 如果只授权访问 chat.db（早期版本要求如此）， 就无法读取该日志，因此在检查点完成之前会缺少最新消息。 如果你在早期版本中授权了 chat.db，信息仍会使用上一个检查点的数据； 在 iMCP 菜单中关闭再开启“信息”，即可改为授权整个文件夹。

附件文件则另当别论。 沙盒会阻止通过授权父文件夹来访问 ~/Library/Messages/Attachments， 因此读取消息附件（messages_attachment_read） 时会通过同一个选择器请求访问该子文件夹—— 需要单独进行第二次只读授权。 授权并非必需： 如果拒绝，messages_attachment_read 将无法读取文件， 但其他功能仍可正常使用。 如果你在支持附件之前就授权了“信息”文件夹， 请在 iMCP 菜单中关闭再开启“信息”，系统便会再次询问是否授权该文件夹。

不过，打开 iMessage 数据库只是成功了一半。 过去几年里， Apple 已逐渐不再以纯文本形式存储消息， 而是转向专有的 typedstream 格式。

我们为这个项目创建了 Madrid： 一个用于读取 iMessage 数据库的 Swift 包。 其中包含用于解码 Apple typedstream 格式的 Swift 实现， 改编自 Christopher Sardegna 的 imessage-exporter 项目 以及关于逆向分析 typedstream 的博客文章。

通话记录数据库访问

从 iPhone 同步的通话记录存储在 ~/Library/Application Support/CallHistoryDB/CallHistory.storedata 这个 SQLite 数据库中。 最近的通话记录位于数据库文件旁边的预写日志中， 因此“电话”服务会要求你打开 CallHistoryDB 文件夹， 而不是只选择数据库文件。

语音留言数据库访问

通过 macOS 26 及更高版本上的“电话”应用从 iPhone 同步的语音留言， 存储在 ~/Library/Group Containers/group.com.apple.FaceTime/com.apple.facetimemessagestored/Data Store/FaceTimeMessageStore-local.sqlitedb 这个 SQLite 数据库中。 该数据库采用预写日志模式，消息音频则位于旁边的 Assets 目录树中，因此“语音留言”服务会要求你打开 Data Store 文件夹， 而不是只选择数据库文件。

语音备忘录资料库访问

“语音备忘录”将资料库存储在 ~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/CloudRecordings.db 这个 SQLite 数据库中。 音频文件位于数据库旁边， 因此“语音备忘录”服务会要求你打开 Recordings 文件夹， 而不是只选择数据库文件。 “语音备忘录”会将每份转录文本写入对应录音的音频文件， 因此只有音频存储在 Mac 上的录音才有转录文本。

我们为这个项目创建了 TSRP： 一个用于读取“语音备忘录”资料库的 Swift 包。 它可以从 .m4a 和 .qta 文件中读取转录文本， 这两种文件将转录文本存储在不同位置。

备忘录数据库访问

Apple 也没有提供访问备忘录的公共 API。 “备忘录”应用将数据存储在 SQLite 数据库中： ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite。 最近的修改位于其预写日志中， 因此“备忘录”服务会要求你打开 group.com.apple.notes 文件夹， 而不是只打开数据库文件。 iMCP 只会读取数据库，不会修改你的备忘录。

每条备忘录的内容都以 gzip 压缩的协议缓冲区形式存储： 先是文本，后面跟着一系列片段，用于标明各部分的格式。 表格单独存储为 CRDT 的状态， 其中列出了行、列，以及每个交叉处的单元格。 使用密码锁定的备忘录经过加密， 因此 iMCP 可以按标题找到它们，但无法读取其内容。

对于这个项目，我们创建了 TopoText： 一个用于读取备忘录数据库的 Swift 包， 名称取自 Apple 对备忘录文本格式的内部称呼。 它基于 Jon Baumann 的 apple_cloud_notes_parser 和 Steve Dunham 的 notesutils 中的逆向工程成果。 “备忘录”服务使用 TopoText 读取备忘录，并以 Markdown 格式返回。

工具结果的 JSON-LD

iMCP 提供的工具会返回 JSON-LD 文档。 例如， fetchContacts 工具使用 Contacts 框架， 该框架使用 CNContact 类型表示个人和组织。 以下是该类型对象编码为 JSON-LD 的示例：

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Mattt",
  "url": "https://mat.tt"
}

对于返回列表的工具，例如 contacts_search， 它会返回一个 JSON-LD 文档，在单个 @context 下通过 @graph 保存列表。 为了缩短结果， 嵌套在其他值中的值（包括图中的值）会省略 @type。

Schema.org 提供了标准词汇，用于表示个人、邮政地址、事件以及我们希望表示的许多其他对象。 JSON-LD 也是一种便捷的编码格式，适用于人类、AI 和传统软件。

对于这个项目，我们创建了 Ontology： 一个用于处理结构化数据的 Swift 包。 它包含 Apple 框架中各类型的便捷初始化器， 例如 iMCP 工具返回的类型。

iMCP Helper

Apple 不会向原生 macOS 应用开放 HomeKit 框架， 只向 Mac Catalyst 应用开放。 因此，Home 服务会在一个单独的 Catalyst 应用中运行， 即 iMCP Helper。 Apple 不允许 Developer ID 应用使用 HomeKit， 因此 iMCP 的发布版本不包含该辅助应用。 请使用你自己的 Apple Developer 账户构建并安装它：

git clone https://github.com/mattt/iMCP.git
cd iMCP
Scripts/install-helper.sh

该脚本使用团队的开发证书对辅助程序进行签名， 并将其安装到 /Applications。 运行它并附加 --help，即可选择其他团队、Bundle ID 或安装目录。 Xcode 必须已登录你的账户（Xcode > Settings > Accounts）， 且辅助程序只能在已注册到你团队的 Mac 上运行。 尚未确认免费个人团队能否使用 HomeKit。 然后在 iMCP 中开启 Home。 iMCP 会在 /Applications 中查找辅助程序。 如果你将它安装在其他位置， 开启 Home 时，iMCP 会要求你选择它， 你也可以在 Settings > Home 中选择它。 启用 Home 时， 如果辅助程序尚未运行，iMCP 会启动它， 而辅助程序会请求 HomeKit 访问权限。 首次运行时，辅助程序的窗口会显示一个八位配对码， 例如 7KQ2-M9XD，以及带编号的步骤： 点击 Copy Code， 点击 Open iMCP… 打开 iMCP 的 Pair with iMCP Helper 窗口， 然后粘贴配对码并点击 Pair。 该按钮会打开 URL imcp://pair，其中不包含任何数据； iMCP 只会为此 URL 打开配对窗口。 辅助程序只会使用 Bundle ID 为 co.dododo.iMCP 的应用打开该 URL， 并优先选择正在运行的副本；如果副本未声明 imcp 方案，则不会使用它； 否则，例如你使用其他 Bundle ID 构建了 iMCP， 辅助程序会提示你改为在 Settings > Home 中选择 Pair…。 如果辅助程序窗口被其他窗口遮挡， 请点击 iMCP 窗口中的 Open iMCP Helper…。 配对码只能使用一次： 配对时，iMCP 会向辅助程序发送一个新的随机密钥， 两个应用都会将该密钥保存在各自的钥匙串中。 输错五次后，辅助程序会显示新的配对码。 若要重新配对，请在辅助程序窗口中点击 Pair Again… 并确认； 辅助程序会结束与 iMCP 的连接，并显示新的配对码和相同步骤。 退出 iMCP 后，辅助程序仍会继续运行； 从其应用菜单中选择 Quit iMCP Helper，或按 Command-Q，即可停止它。 窗口还会报告启动和权限错误。 Mac 的 iCloud 账户必须有权访问该家庭， 且写入操作可能要求账户具有所有者或管理员角色。

Sparkle 会更新 iMCP，但不会更新辅助程序。 更新 iMCP 后， 请从与新版本匹配的标签重新构建辅助程序：

git fetch --tags
git checkout <version>
Scripts/install-helper.sh

较旧版本的辅助程序可能与应用的 Home 工具不匹配。

辅助程序的开发证书和配置描述文件会过期。 两者通常都有效一年， 但证书可能先过期。 运行以下命令可查看配置描述文件的到期日期：

security cms -D -i "/Applications/iMCP Helper.app/Contents/embedded.provisionprofile" |
  plutil -extract ExpirationDate raw -o - -

运行以下命令可查看证书的到期日期：

codesign -d --extract-certificates=/tmp/imcp-helper-cert "/Applications/iMCP Helper.app"
openssl x509 -inform DER -in /tmp/imcp-helper-cert0 -noout -enddate

过了这两个日期中较早的日期后，辅助程序可能无法启动。 再次运行 Scripts/install-helper.sh 以续期； 旧证书和配置描述文件过期后，该脚本会让 Xcode 创建新的证书和配置描述文件。

首次运行时，配置可能会因“PLA Update available”而失败。 团队的 Account Holder 必须在 Apple Developer 账户中接受最新的 Program License Agreement。 如果你无法写入 /Applications（例如，使用非管理员账户）， 安装可能会因权限错误而失败。 改为使用 --destination ~/Applications 运行脚本。 随后，iMCP 会要求你选择辅助程序。

两个应用都会从 Shared/Home/HomeTools.swift 编译相同的工具定义。 辅助程序使用 HomeKit 实现这些工具； 应用会通过回环接口上的 MCP 连接转发每次调用， 因此常规服务开关和单个工具开关均适用。 对象 ID 为 HomeKit UUID 字符串。 只有在 include_values 为 true 时，资源清单工具才会返回实时特征值， 读取超时时间为五秒，且同时最多执行四次 HomeKit 读取。 连接丢失后，只读调用会重试一次。 写入操作不会重复执行，因为 HomeKit 可能已经应用了这些操作； 错误信息会要求调用方先检查家庭状态，再进行重试。 helper 会在仅限本地的 DNS-SD 接口上发布 "_imcp-helper._tcp"，iMCP 会在那里发现它，无论 helper 是否由 iMCP 启动。 如果有多个 helper 正在运行，iMCP 会先尝试所选位置的 helper，然后再尝试其他 helper。 连接使用 TLS，并将配对密钥用作预共享密钥，因此没有该密钥的连接会在 TLS 握手时失败。 密码套件还会添加 ECDHE 密钥交换，因此即使日后密钥或代码被发现，录制的连接仍会保密。 配对连接使用由代码通过 PBKDF2 派生的密钥，这会让冒充 helper 发布自身并在你配对时进行的进程难以快速猜测。 如果你使用较早版本的 iMCP 构建了 helper，请退出它，并使用 Scripts/install-helper.sh 重新构建；iMCP 会拒绝未声明当前协议版本的 helper。 在 iMCP 中启用 Home 后，uv run Scripts/check-home.py <path-to-imcp-server> 会通过 iMCP 运行只读集成检查。

构建 helper

构建 iMCP scheme 时会运行 Scripts/build-helper.sh，该脚本会在独立的派生数据目录中构建适用于 Mac Catalyst 的 iMCP Helper scheme，并将生成的产品复制到 app 中。 直接的目标依赖会选择 helper 的 iOS 变体，因此必须进行嵌套构建。 Release 构建会设置 EMBED_HOME_HELPER = NO，并将 helper 排除在外。

HomeKit 权限需要开发证书，以及包含 HomeKit 功能的配置描述文件。 因此，即使原生 Debug app 未签名，helper 在 Debug 和 Release 中都会使用团队 TTY35UM57S 进行自动签名。 要使用其他团队构建，请在 helper 目标的 Signing & Capabilities 标签页中更改团队。 新 bundle ID 的首次 Mac Catalyst 构建可能会失败，并显示错误 "Entitlement com.apple.developer.homekit not found and could not be included in profile"，因为自动配置只会为 iOS 目标注册该功能。 Scripts/install-helper.sh 会先为 iOS 构建一次，然后重试，以处理此问题。 要手动执行，请先为 iOS 构建一次 helper 以注册该功能，然后再为 Mac Catalyst 构建：

xcodebuild -scheme "iMCP Helper" -destination "generic/platform=iOS" \
  -allowProvisioningUpdates build
xcodebuild -scheme "iMCP Helper" -destination "platform=macOS,variant=Mac Catalyst" \
  -allowProvisioningUpdates build

CI 会以未签名方式构建两个 app，这可以检查编译和打包，但无法访问 HomeKit：

xcodebuild -scheme iMCP -configuration Debug -destination "platform=macOS" \
  CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO \
  HELPER_CODE_SIGNING_ALLOWED=NO build

调试

允许访问本地网络

imcp-server 使用 Bonjour 查找 iMCP app，因此需要获得访问本地网络的权限。 imcp-server 在“系统设置”>“隐私与安全性”>“本地网络”中有自己的条目，与 iMCP 以及运行它的 app（例如终端）分开。 如果关闭该条目，imcp-server 将无法找到 app，并会报告 Bonjour 服务发现超时。

使用 MCP Inspector

要调试 iMCP 与客户端之间的交互，可以使用 Inspector 工具（需要 Node.js）：

1. 点击 >“将服务器命令复制到剪贴板”

2. 打开终端并运行以下命令：

   # Download and run inspector package on imcp-server
   npx @modelcontextprotocol/inspector [paste-copied-command]
   
   # Open inspector web app running locally
   open http://127.0.0.1:6274
   

Inspector 可让你查看客户端与 iMCP 服务之间的所有请求和响应，有助于理解协议的工作方式。

使用 Companion

Companion 是一款用于测试和调试 MCP 服务的实用工具（需要 macOS 15 或更高版本）。 它让你可以轻松浏览和交互服务的提示词、资源和工具。 以下是将它连接到 iMCP 的方法：

1. 点击 >“将服务器命令复制到剪贴板”
2. 下载并打开 Companion app
3. 点击工具栏中的 + 按钮以添加 MCP 服务
4. 填写表单：
   • 输入“iMCP”作为名称
   • 选择“STDIO”作为传输方式
   • 粘贴复制的 iMCP 服务命令
   • 点击“添加服务”

• 感谢 Justin Spahr-Summers (@jspahrsummers)、 David Soria Parra (@dsp-ant) 和 Ashwin Bhat (@ashwin-ant) 为 MCP 所做的工作。
• 感谢 Christopher Sardegna (@ReagentX) 对 Messages 应用使用的 typedstream 格式进行逆向工程。

许可证

本项目采用 MIT 许可证。 更多信息请参阅 LICENSE 文件。

法律声明

iMessage® 是 Apple Inc. 的注册商标。 本项目与 Apple Inc. 无关，也未获其认可或赞助。