Mac Messages MCP

使用 Claude、Codex、Cursor、VS Code 或任意本地 MCP 客户端，通过 macOS「信息」应用搜索、读取和发送消息。

Mac Messages MCP 在你的 Mac 上本地运行。它以只读方式打开「信息」和「通讯录」数据库，仅返回客户端请求的数据；只有客户端明确调用发送工具时，才会使用「信息」应用自动化功能。

重要

此服务仅适用于 macOS。读取消息需要“完全磁盘访问权限”。发送消息需要 Mac 已登录「信息」，并且允许启动此服务的应用自动化操作「信息」。

工作原理

flowchart LR
    A[MCP client] -->|stdio| B[mac-messages-mcp]
    B --> C{Tool call}
    C -->|read tools| D[(chat.db read-only)]
    C -->|read tools| E[(AddressBook read-only)]
    C -->|send tools| F[Messages.app]
    F --> G[Recipient]
    D --> H[Untrusted-output boundary]
    E --> H
    H --> A

客户端读取的所有内容均来自以只读方式打开的本地 SQLite 数据库。离开设备的所有内容均通过「信息」应用发出，且必须由明确的发送工具调用触发。返回给模型的消息和联系人相关文本会被标记为不可信数据。

功能

领域	Mac Messages MCP 提供的功能
读取	获取所有对话的最近消息，或按联系人、群聊、日期范围或未读状态筛选；支持通过 limit/offset 分页，以及使用前向游标读取
对话	获取所有对话（1:1、商家和群聊），包括类型、消息和未读计数、最近活动，以及等待新消息的阻塞式等待
搜索	在指定时间范围或全部历史记录中模糊搜索消息正文，并限定联系人或对话范围
上下文	获取每条消息的服务类型（iMessage/SMS/RCS）、未读和送达状态、Tapback 反馈及线程回复
联系人	按近似姓名模糊查找联系人、获取可用于发送的电话号码，以及创建联系人
群聊	查找有名称的群聊，并获取可在读取和发送时重复使用的稳定聊天 ID
发送	发送 iMessage，失败时回退到 SMS/RCS；支持文件附件、通过 MCP 征询功能请求人工批准，以及检查 iMessage 可达性
定时发送	在服务进程持续运行期间，将消息排入队列以便稍后发送
附件	搜索元数据，尽力搜索文本/PDF 内容，内嵌显示图片（将 HEIC 转换为 PNG），并为较大的文件或非图片文件提供本地路径
诊断	在 MCP 客户端内检查「信息」和「通讯录」数据库的访问权限
隐私	以只读方式访问 SQLite；不保存消息归档；设置结构化的不可信输出边界

快速开始

1. 安装 uv

brew install uv

确认启动器可用：

uvx --version

需要 Python 3.10 或更高版本。uvx 可以安装兼容的 Python，并在隔离环境中安装 Mac Messages MCP，因此无需先创建虚拟环境。

2. 授予 macOS 权限

打开 系统设置 → 隐私与安全性 → 完全磁盘访问权限，并启用将启动 MCP 服务的应用：

• 在相应应用中配置时，启用 Claude Desktop、Cursor、VS Code 或 ChatGPT 桌面应用
• 从终端使用 Claude Code 或 Codex CLI 时，启用 Terminal、iTerm2、Ghostty 或其他终端

更改完全磁盘访问权限后，退出并重新打开应用。首次查找联系人或发送消息时，macOS 可能会另外询问是否允许访问“通讯录”或控制“信息”。请允许这些请求。

还要确保“信息”App 已打开、已登录，并且能够正常发送普通消息。

3. 将服务添加到 MCP 客户端

所有客户端使用相同的服务命令：

uvx mac-messages-mcp

在下方选择你的客户端。

Claude Desktop

打开 Claude → 设置 → 开发者 → 编辑配置，然后添加：

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

保留 claude_desktop_config.json 中已有的其他服务，保存文件，然后重新启动 Claude Desktop。

Claude Desktop 还支持可安装的 .mcpb 扩展。如果想将此代码库打包成扩展，请参阅构建 Claude Desktop 扩展。

Claude Code

在用户级别添加一次，即可在每个项目中使用：

claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp

验证配置：

claude mcp get mac-messages

在 Claude Code 中运行 /mcp，检查连接和工具。

Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用

同一台 Mac 上的 Codex 客户端共用 MCP 配置。使用以下命令添加服务：

codex mcp add mac-messages -- uvx mac-messages-mcp

然后验证：

codex mcp list

你也可以将其直接添加到 ~/.codex/config.toml：

[mcp_servers.mac-messages]
command = "uvx"
args = ["mac-messages-mcp"]

更改配置后，重新启动桌面应用或 IDE 扩展。在 Codex CLI 中，使用 /mcp 查看当前启用的服务。

Cursor

或者打开 Cursor 设置 → 工具与 MCP → 新建 MCP 服务，然后使用：

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

保存后，从 Cursor 的 MCP 设置中重新启动服务。

VS Code / GitHub Copilot

打开命令面板并运行 MCP: 添加服务。选择 命令（stdio），将 uvx 设为命令，将 mac-messages-mcp 设为参数，然后全局安装。

也可以在终端中添加：

code --add-mcp '{"name":"mac-messages","command":"uvx","args":["mac-messages-mcp"]}'

对应的用户级或工作区级 mcp.json 条目如下：

{
  "servers": {
    "mac-messages": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

说明

VS Code 使用顶层 servers 对象。Claude Desktop 和 Cursor 使用 mcpServers。

其他 stdio MCP 客户端

使用以下通用服务定义：

{
  "command": "uvx",
  "args": ["mac-messages-mcp"]
}

如果 GUI 客户端提示找不到 uvx，请在终端中运行 which uvx，并将 "uvx" 替换为返回的绝对路径。在 Apple 芯片 Mac 上，Homebrew 通常会将其安装到 /opt/homebrew/bin/uvx；在 Intel Mac 上，通常会安装到 /usr/local/bin/uvx。

4. 验证连接

让客户端依次调用 tool_check_db_access 和 tool_check_addressbook。两者都成功后，尝试以下提示词：

Show me my messages from the last two hours.

Find messages from Carter about dinner in the last 30 days.

Find PDFs sent to me this month, but do not open any yet.

Find Jordan in my contacts and draft a message saying I am running 10 minutes
late. Do not send it until I confirm.

首次启动 uvx 时，可能需要更长时间，因为它会下载并缓存 Python 依赖项。

5. 可选：设置电话号码地区

国家格式的电话号码（06 39 98 00 01、(415) 555-1234）必须先转换为 E.164 格式，才能与 Messages 数据库中的号码匹配；转换时需要知道号码所属的国家。因此，服务会读取你的 Mac 地区设置。Mac 配置正确时，无需进行任何操作。

当电话号码所属地区与 Mac 的配置不同（例如，在地区设为 en_US 的 Mac 上使用法国 SIM 卡）时，请将 MAC_MESSAGES_REGION 设为 ISO 3166-1 alpha-2 代码：

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"],
      "env": { "MAC_MESSAGES_REGION": "FR" }
    }
  }
}

对于 Claude Code：

claude mcp add --transport stdio --scope user \
  --env MAC_MESSAGES_REGION=FR \
  mac-messages -- uvx mac-messages-mcp

地区只会在启动时解析，因此更改后请重启服务。解析顺序为：MAC_MESSAGES_REGION，然后是 macOS 的 AppleLocale 偏好设置，再然后是 LC_ALL / LC_CTYPE / LANG，最后是 US。已经采用 E.164 格式的号码（+33639980001）不会重新解析，无需进行上述设置。

可用工具

工具	用途	副作用
tool_get_recent_messages	读取近期消息，可按联系人、群聊 ID、日期范围或未读状态筛选；使用 limit/offset 分页	只读
tool_fuzzy_search_messages	按近似文本匹配搜索消息正文，可限定联系人或聊天；默认搜索 30 天，或设置 hours=0	只读
tool_list_conversations	列出所有对话及其类型、消息数、未读数和最近活动	只读
tool_wait_for_new_messages	阻塞等待 ROWID 游标之后的新消息，或直到超时	只读
tool_find_contact	在通讯录中模糊匹配姓名并返回电话号码	只读
tool_get_chats	列出已命名的群聊及其标识符	只读
tool_search_attachments	按日期、联系人、MIME 类型和数量限制查找附件元数据	只读
tool_search_attachment_contents	按日期、联系人和 MIME 类型搜索附件文本或 PDF 内容	只读
tool_get_attachment	按 ID 获取一个附件；支持时以内嵌方式返回，否则返回本地路径	只读
tool_check_imessage_availability	检查某个电话号码或电子邮件地址是否可能支持 iMessage	只读
tool_check_db_access	诊断对 ~/Library/Messages/chat.db 的访问情况	只读
tool_check_contacts	返回联系人数量和少量示例	只读
tool_check_addressbook	诊断对通讯录/AddressBook 数据库的访问情况	只读
tool_send_message	通过 Messages.app 发送一条单聊或群聊消息，可选附加文件并征求确认	发送真实消息
tool_create_contact	在 Contacts.app 中创建一个包含电话号码的联系人条目	更改通讯录
tool_schedule_message	在此服务进程运行期间将消息加入队列，以便稍后发送	稍后发送真实消息
tool_list_scheduled_messages	列出进程内的定时消息队列及其状态	只读
tool_cancel_scheduled_message	取消一条待发送的定时消息	只读
服务器附带三个 MCP 提示词：triage_unread_messages、
summarize_recent_messages 和 draft_reply。它们是起点，用于告诉
Agent 应调用哪些读取工具，并且绝不会发送任何内容。

服务器还公开了两个 MCP 资源：

• messages://recent/{hours}
• messages://contact/{contact}/{hours}

消息元数据、分页和游标

如果消息行中包含相关数据，读取操作会附加简洁标签，让旧数据库或不完整数据库的输出保持不变：

[2026-10-01 09:14:02] Alice [iMessage] [unread]: running late, sorry
[2026-10-01 09:15:40] You [iMessage] [not delivered]: no worries
[2026-10-01 09:15:55] Alice [iMessage] [tapback: liked]: (reaction)
[2026-10-01 09:16:10] Bob [SMS] [reply]: got it

当页面已满时，tool_get_recent_messages 会在末尾附注，指出下一个要使用的 offset。传入 since_rowid 后，它会切换为向前游标读取（按时间从早到晚）， 并忽略 hours 时间范围；tool_wait_for_new_messages 轮询时就采用这种模式。

它有意不做的事

Messages.app 自动化不支持以下操作，因此服务器会拒绝，而不会假装可以执行：

• 发送 Tapback、消息效果或主题行（只能发送文本和文件附件）
• 创建群聊、添加或移除参与者，或向群聊附加文件
• 编辑、撤回、删除或标记消息为已读，以及保存草稿
• 编辑或合并现有的 Contacts 卡片（tool_create_contact 会创建新卡片）
• 定时发送依赖服务器进程持续运行；由于不会持久化，如果客户端先断开连接，定时消息就会丢失

Agent 技能

此仓库附带一项 Agent 技能， 用于告诉 Agent 何时以及如何调用各个工具：先检查访问权限、列出对话、 解析收件人或群聊、搜索消息文本或附件内容、分页查看附件、确认发送、 安排稍后发送，以及将消息衍生的输出视为不可信数据。在此仓库中工作时， Claude Code 会自动发现它。

若要在其他项目中使用，请将技能目录复制到该项目的 .claude/skills/ 中，或复制到 ~/.claude/skills/，以便随处使用：

mkdir -p ~/.claude/skills
cp -R .claude/skills/mac-messages ~/.claude/skills/

使用联系人、聊天和附件

收件人

对于直接消息，E.164 电话号码是最可靠的格式：

+14155551234

国家格式的号码也可以使用。系统会根据 Mac 的配置区域将其转换为 E.164 格式，因此，在美国 Mac 上，(415) 555-1234 会变成 +14155551234；在法国 Mac 上，06 39 98 00 01 会变成 +33639980001。如果号码所属区域与 Mac 的配置区域不同，请将 MAC_MESSAGES_REGION 设为 ISO 3166-1 alpha-2 代码 （MAC_MESSAGES_REGION=GB）。已经是 E.164 格式的号码绝不会被重新解释。

服务器还接受电子邮件地址、联系人姓名，以及在联系人搜索结果不明确时返回的 contact:N 选项。

对于群组对话，请调用 tool_get_chats，将其聊天 ID 传给 tool_send_message，并设置 group_chat=true。使用同一 ID 作为 tool_get_recent_messages 中的 chat_id，即可读取该对话。

附件

附件访问有意分为三个步骤：

1. 消息读取和搜索会添加简洁标记，例如 [attachments: #42 image/jpeg (invitation.jpg)]。
2. tool_search_attachments 会搜索元数据，但不会加载文件内容。
3. tool_get_attachment 会获取选定的一个附件。

默认情况下，大小不超过 5 MB 的图像会以内嵌形式返回。HEIC 图像会转换为 PNG。较大的图像、PDF、视频和音频会以本地文件系统路径的形式返回，由 MCP 客户端决定是否打开。贴纸、链接预览负载以及 .pluginPayloadAttachment 容器会被过滤掉。

架构

Mac Messages MCP 是一个小型 Python 包，每个模块负责一项工作：

mac_messages_mcp/
  server.py       FastMCP server: tools, prompts, resources, stdio transport
  cli.py          mac-messages-cli terminal interface
  messages.py     chat.db reads and AppleScript sends for Messages.app
  content.py      Best-effort text/PDF attachment content search
  phone.py        E.164 normalization against the Mac's configured region
  scheduler.py    In-process scheduled-send queue
  untrusted.py    Structural neutralization of Messages/Contacts-derived text
scripts/
  build_mcpb.py   Builds the Claude Desktop .mcpb extension
  bump_version.py Keeps version metadata in sync across release files
tests/            Pytest suite over temporary databases and mocked AppleScript
main.py           Stdio entry point for MCP clients
manifest.json     MCPB manifest for the Claude Desktop extension

读取操作直接访问 chat.db 和 AddressBook 数据库；发送操作则通过 AppleScript 调用 Messages.app。面向模型的负载在到达客户端之前会先经过 untrusted.py。

隐私与安全

• Messages 和 Contacts 的 SQLite 连接使用只读模式和 SQLite query_only。
• 服务不会上传、镜像、索引或维护自己的消息存档。
• 结果会写入客户端启动的本地 MCP stdio 连接。
• 源自 Messages/Contacts 的工具和资源输出会进行结构化中和（嵌入的换行符和 ASCII 控制字符无法构成额外的对话记录行；不可见字符、格式字符和双向文本字符会以转义形式显示），并在显式的 <untrusted-mcp-output> 块中返回。 这并不能保证防止注入：第三方 iMessage/SMS 内容仍可能尝试提示词注入。服务会将这类内容处理为非结构化文本并加以标记；客户端不得将其视为授权、确认或工具指令。
• 只有在明确获取后才会返回附件字节，且内嵌图像的大小有限制。文件名、MIME、路径和其他元数据文本会使用相同的边界进行中和；图像载荷会保留原样。
• 发送操作仅由 tool_send_message 执行，该工具会转义 AppleScript 输入，并使用有界执行超时。此服务不会执行人工确认；MCP 客户端必须对发送操作进行把关。
• 完全磁盘访问权限的范围大于 Messages 访问权限。只向你信任的 MCP 客户端授予此权限，并在批准发送前检查目标对象。

请参阅 SECURITY.md，以私下报告漏洞。

故障排除

uvx 或 spawn uvx ENOENT

图形界面应用无法访问 shell 的 Homebrew 路径。请运行：

which uvx

将该完整路径用作 MCP command，然后重启客户端。

Operation not permitted、unable to open database file 或没有消息

向启动服务的应用授予完全磁盘访问权限，而不仅仅是向 Messages.app 授权。之后完全退出并重新打开启动器，然后再次调用 tool_check_db_access。

对于 Claude Code 或 Codex CLI，启动器通常是你的终端。对于桌面应用或 IDE 集成，启动器通常是 Claude Desktop、Cursor、VS Code 或 ChatGPT 桌面应用本身。

联系人为空或联系人查询失败

如果 macOS 弹出提示，请允许启动应用访问 Contacts。确认已授予完全磁盘访问权限，重启应用，然后依次调用 tool_check_addressbook 和 tool_check_contacts。

如果联系人已列出，但其号码带有错误的国家代码，则服务正在根据错误的地区扩展你的国家格式号码。请将 MAC_MESSAGES_REGION 设置为正确的 ISO 3166-1 alpha-2 代码，然后重启服务。

可以读取，但发送失败

1. 打开 Messages.app，手动发送一条消息，以确认账户和收件人正常。
2. 检查系统设置 → 隐私与安全性 → 自动化，并允许启动应用控制 Messages。
3. 对于直接收件人，优先使用 E.164 格式的号码，例如 +14155551234。
4. 使用 tool_check_imessage_availability 检查可能的发送路径。

已列出附件，但无法打开

macOS 将文件转存后，Messages 可能仍会保留数据库元数据。请在 Messages.app 中打开对话并下载附件，然后重试 tool_get_attachment。

在终端中运行时服务似乎卡住

这是 MCP stdio 服务的正常行为：它会等待客户端发送协议输入。请查看客户端的 MCP 状态视图，或启动 MCP Inspector：

yarn dlx @modelcontextprotocol/inspector uvx mac-messages-mcp

安装为独立工具

MCP 客户端可以通过 uvx 直接启动此软件包；也可以选择永久安装。

uv tool install mac-messages-mcp
mac-messages-mcp

使用以下命令升级或移除：

uv tool upgrade mac-messages-mcp
uv tool uninstall mac-messages-mcp

Python API

MCP 服务是主要接口，但此软件包也导出其核心读取和发送函数：

from mac_messages_mcp import get_recent_messages, send_message

recent = get_recent_messages(hours=48)
print(recent)

result = send_message(
    recipient="+14155551234",
    message="Hello from Mac Messages MCP!",
)
print(result)

这些调用使用相同的 macOS 权限，也可以发送真实消息。

命令行界面

此软件包还会安装 mac-messages-cli 命令，因此无需 MCP 客户端，即可在终端中读取、搜索和发送 Messages。它使用相同的本地数据库，并需要与服务相同的 macOS 权限；为终端授予“完全磁盘访问权限”即可满足两者的需求。

uv tool install mac-messages-mcp
mac-messages-cli --help

命令	用途
recent	查看最近的消息，可按联系人或群聊 ID 筛选。
search TERM	在指定时间范围内模糊搜索消息文本。
contact NAME	在通讯录中模糊匹配姓名，并输出可用于发送的号码。
contacts	显示联系人数量以及部分 AddressBook 条目。
chats	查看已命名的群聊及其标识符。
attachments	按日期范围、联系人和 MIME 类型查看附件元数据。
attachment ID	查看单个附件的元数据和本地路径，可选使用 --save。
send	通过 Messages.app 发送一条消息。
check	检查 Messages/AddressBook 访问权限和 iMessage 连通性。

# Last 48 hours, or one contact, or one group chat
mac-messages-cli recent -n 48
mac-messages-cli recent --contact "Jordan"
mac-messages-cli recent --chat chat721054478304420871

# Fuzzy search: last 30 days by default, or all history with -n 0
mac-messages-cli search "dinner" -t 0.7
mac-messages-cli search "dinner" -n 0

# Contacts and group chats
mac-messages-cli contact "Jordan"
mac-messages-cli chats

# Attachments: search metadata, then fetch or save one file
mac-messages-cli attachments --since 2026-09-01 --mime image/ --limit 20
mac-messages-cli attachment 42 --save ~/Desktop/invitation.jpg

# Permissions and iMessage reachability
mac-messages-cli check --recipient +14155551234

# Sending prompts for confirmation unless --yes is passed
mac-messages-cli send +14155551234 "Running 10 minutes late."

mac-messages-cli send 会在发送前要求确认 y/N。当标准输入不是终端时，除非传入 --yes，否则它会拒绝发送，因此无人值守的脚本不会意外发送消息。查找失败时，命令会以非零状态码退出，因此可以在脚本中安全地根据输出采取不同操作。

开发

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

uv sync --frozen --extra dev
uv run pytest
uv run black --check .
uv run isort --check-only .
uv build

测试会模拟 AppleScript，并使用临时数据库夹具；绝不能读取贡献者的真实 Messages 或 Contacts 数据。贡献检查清单请参阅 CONTRIBUTING.md，发布相关内容请参阅 VERSIONING.md。

构建 Claude Desktop 扩展

此代码仓库包含一个 MCPB manifest.json 和一个构建脚本，可将架构专用的 uv 二进制文件打包：

yarn global add @anthropic-ai/mcpb
uv run python scripts/build_mcpb.py

构建 Intel 版本：

uv run python scripts/build_mcpb.py --arch x86_64

通过 Claude Desktop → Settings → Extensions → Advanced settings → Install Extension… 安装生成的 .mcpb。打包后的扩展在首次启动时仍需要网络访问权限，以便下载 Python 和软件包依赖项。

使用 --no-bundle 可将扩展打包为依赖系统中的 uv；也可以运行 uv run python scripts/build_mcpb.py --help 查看所有选项。

Docker

随附的 Dockerfile 用于验证软件包和目录。Linux 容器无法访问 macOS TCC 权限，也无法自动操作 Messages.app，因此不支持通过 Docker 在主机 Mac 上读取或发送消息。

文档

文档	用途
Agent 技能	Agent 应在何时以及如何调用各个工具
贡献指南	开发工作流、检查和拉取请求规范
安全	私密漏洞报告和信任模型
版本管理	发布和版本元数据流程
变更日志	按版本列出的面向用户的变更

贡献

欢迎提交问题和针对性拉取请求。请勿在错误报告或测试夹具中包含真实消息内容、联系人、电话号码、数据库文件或附件。

许可证

MIT © Carter Lasalle