Apple Contacts

Apple Contacts MCP

适用于 macOS 上 Apple Contacts 的 MCP 服务。

提供联系人访问功能，用于查询、搜索和解析收件人。发送消息前，先使用此服务将姓名解析为电话号码或电子邮件地址。

适用场景

• 仅涉及联系人的工作流
• 发送消息前验证收件人
• 与一体化服务分开的联系人查询

功能

• 列出和搜索联系人
• 查询完整联系人详情
• 解析消息收件人
• 为上下文受限的客户端提供工具发现辅助功能 search_tools 和 get_tool_info
• 创建、更新和删除联系人
• 检测重复联系人并建议合并候选项（contacts_find_duplicates、contacts_suggest_merge_candidates）
• 编辑带标签的电话号码和电子邮件方式
• 目录资源和收件人检查提示词
• 健康状态和权限检查：contacts_health、contacts_permission_guide、contacts_recheck_permissions

在这台 Mac 上安装

uvx apple-contacts-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

在 AI Agent 中安装

{
  "mcpServers": {
    "apple-contacts": {
      "command": "uvx",
      "args": ["apple-contacts-mcp"],
      "env": {
        "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage"
      }
    }
  }
}

claude mcp add --transport stdio --scope user apple-contacts -- uvx apple-contacts-mcp

安全模式

• safe_readonly
• safe_manage
• full_access

传输方式

默认且推荐使用 stdio 传输方式。设置 APPLE_CONTACTS_MCP_TRANSPORT=streamable-http（可选设置 APPLE_CONTACTS_MCP_HOST 和 APPLE_CONTACTS_MCP_PORT）即可改用 Streamable HTTP 服务。

搜索行为

姓名和组织搜索使用 Contacts.app 的筛选查询。姓名无匹配时会返回空结果，不会扫描整个通讯录。对于包含数字／标点基底的电话号码查询（包括可识别的分机后缀 ext、ext.、extension、extn.、x、# 和 ;ext=，以及可选的 tel: 前缀），会保留分页目录回退机制，以匹配联系方式值。包含 @ 的电子邮件查询也会保留该机制。分机匹配会将基底号码和分机分开，要求分机完全匹配，并允许匹配本地号码后缀。收件人解析会选择匹配的电话方式，并拒绝存在多个不同匹配方式的情况。

Contacts 返回的字面控制字符和复杂表情符号会在 Python 端解码，且文本内容保持不变。

macOS 权限

• 需要通讯录访问权限
• contacts_health 会读取原生授权状态，不会请求访问权限，也不会读取联系人。permission_status 会区分已授权、未知、已拒绝和检查失败。AppleScript 后端会报告授权状态未知，且不会发送 Apple 事件。明确的 Contacts 操作仍会执行其权限检查。

启动检查清单

• 将 uvx apple-contacts-mcp（或克隆仓库中的 AppleContacts-MCP/start.sh）添加到 MCP 客户端
• 重新加载或重新连接客户端，使 Contacts 工具集加载到上下文中
• 首先调用 contacts_health
• 如果通讯录访问受阻，调用 contacts_permission_guide
• 更改 macOS 权限后，调用 contacts_recheck_permissions

提示词说明

• tools/list 会返回完整的 Contacts 工具集。上下文受限的客户端可以先使用 search_tools，然后对所需的 Contacts 工具使用 get_tool_info。
• 用户提供人物姓名时，在执行任何 iMessage 或 Mail 操作之前，先运行 Contacts。
• 执行操作前，先按姓名、电话号码或电子邮件地址查找联系人。
• 如果匹配到多个联系人，请先确认目标对象，再发送消息。
• 更新联系人时，只有在打算替换相应类型的全部信息时，才传入明确的 phones 或 emails 数组。
• 通过 Messages 或 Mail 联系某人之前，请确保该联系人保留了带标签的电话号码或电子邮件地址。

相关

• Apple-Tools-MCP

原生 Contacts 访问

Contacts 默认使用 CNContactStore，因此读写操作无需等待 Contacts.app。首次使用时，会通过 Xcode Command Line Tools 编译打包的 Swift 助手，并在 ~/.apple-mcps/build 下缓存经过签名的应用包 Apple Contacts MCP Helper。设置 APPLE_CONTACTS_MCP_HELPER_BUILD_DIR 可指定其他构建目录。如果运行 MCP 服务的应用已获得 Contacts 访问权限，则会使用该权限；否则，macOS 会询问是否允许 Apple Contacts MCP Helper 访问 Contacts。请参阅日历、提醒事项和通讯录：macOS 会向谁请求权限。

设置 APPLE_CONTACTS_MCP_BACKEND=applescript 可使用先前的后端。原生后端会直接返回名字和姓氏，并保留电话/电子邮件更新语义：省略一个集合即可保留它，传入 [] 则会清除它。联系人备注需要单独的 macOS 权限；原生写入前会拒绝非空的 note。AppleScript 后端仍可用于备注。

该助手还会通过一次遍历通讯录，针对 lookup_handles（电话号码或电子邮件地址组成的 JSON 数组）返回可能归属这些信息的联系人。与其他命令不同，它不会请求访问权限：未获授权时会返回 PERMISSION_DENIED 或 AUTHORIZATION_UNKNOWN。AppleContactsBridge.lookup_handles 会对这些结果应用 phone_matching 的精确归属规则；只有在助手已构建时，Apple-Tools-MCP 才会用它为 Messages 联系方式标注姓名。它不会作为 MCP 工具公开。

原生助手会将不可变的源代码快照编译为一个应用包，并以完整的 SHA-256 哈希值命名。编译期间如果源代码发生变化，构建会被拒绝；并发构建也无法替换已安装的应用包。不同版本的源代码会保留各自的可执行文件，但使用相同的应用包标识符。该助手采用临时签名，因此源代码更新后，macOS 可能会再次询问一次。

原生助手改编自 Jaume Puig 在 JaumeAP/Apple-MCPs 中的工作。