Mac消息MCP
使用MCP（多上下文协议）与macOS Messages应用程序交互的Python桥。
快速安装
对于游标用户
*单击上面的按钮自动将Mac消息MCP添加到光标*
适用于Claude桌面用户
看 集成部分 下面是安装说明。
特性
- 通用消息发送：根据收件人的可用性通过iMessage或SMS/RCS自动发送
- 智能回退：当iMessage不可用时，无缝回退到短信（非常适合Android用户）
- 消息阅读：从macOS messages应用程序读取最近的消息
- 联系人筛选：按特定联系人或电话号码筛选邮件
- 群聊过滤：使用来自的聊天ID
tool_get_chats按时间顺序阅读一组对话 - 模糊搜索：通过智能匹配搜索消息内容
- 附件：查找和查看对话中共享的照片、PDF和其他附件
- iMessage检测：发送前检查收件人是否有iMessage
- 交叉平台的：适用于iPhone/Mac用户（iMessage）和Android用户（SMS/RCS）
使用附件
附件访问使用 渐进式披露 --发现是廉价的，获取是深思熟虑的：
- 第1层——邮件搜索中的发现。
tool_get_recent_messages和tool_fuzzy_search_messages用简洁的摘要注释有附件的邮件，如[attachments: #42 image/jpeg (invitation.jpg)]id允许您稍后获取文件。 - 第2层——附件优先搜索。
tool_search_attachments(start_date, end_date, contact, mime_type, limit)仅返回元数据（id、MIME类型、文件名、大小、发件人），这对于“查找伊丽莎白在2026年4月发送的所有图像”而不扫描邮件文本非常有用。 - 第三层——取回。
tool_get_attachment(attachment_id)返回文件。图像MIME类型内联返回（HEIC转换为PNG，因此可以直接查看）。PDF、视频和音频作为文件系统路径返回，代理可以使用自己的工具读取。默认情况下，内联图像字节的上限为5MB，以避免上下文爆炸；过大的图像会回退到路径返回。
贴纸、链接预览“气球”有效载荷，以及 .pluginPayloadAttachment 默认情况下，容器会被过滤掉。
收件人格式
对于直接发送，E.164电话号码带有前导 + 是最可靠的格式，例如 +14155551234。带有国家代码的裸数电话号码在发送前会进行标准化处理，10位美国号码则按以下方式发送 +1.... tool_find_contact 以相同的发送就绪格式返回电话匹配。
先决条件
- macOS（在macOS 11+上测试）
- Python 3.10+
- uv包管理器
安装uv
如果你在Mac上，请使用Homebrew安装uv：
brew install uv否则，请按照上的安装说明进行操作 uv网站.
⚠️ 安装uv之前不要继续
安装
完整磁盘访问权限
⚠️ 此应用程序需要 全磁盘访问 允许您的终端或应用程序访问Messages数据库。
要授予全磁盘访问权限，请执行以下操作：
- 打开 系统首选项/设置 > 安全与隐私/隐私 > 全磁盘访问
- 单击锁图标进行更改
- 将您的终端应用程序（终端、iTerm2等）或Claude Desktop/Cursor添加到列表中
- 授予权限后重新启动终端或应用程序
整合
Claude桌面集成
选项1:克劳德桌面扩展
此回购包括一个兼容MCPB的 manifest.json Claude Desktop的一键扩展流程。
yarn global add @anthropic-ai/mcpb
mcpb pack安装生成的 .mcpb 来自Claude Desktop的文件 设置 > 扩展 > 高级设置 > 安装扩展。...
Claude Desktop，或用于打包/运行扩展的终端，仍然需要完全磁盘访问权限来读取消息。
选项2：手动配置
- 首选 克劳德 > 设置 > 开发者 > 编辑配置 > claude_desktop_config json
- 添加以下配置：
{
"mcpServers": {
"messages": {
"command": "uvx",
"args": [
"mac-messages-mcp"
]
}
}
}光标集成
选项1：一键安装（推荐）
选项2：手动设置
首选 光标设置 > 主控程序 并将其粘贴为命令：
uvx mac-messages-mcp⚠️ 只运行一个MCP服务器实例（在Cursor或Claude Desktop上），而不是两者都运行
Docker容器集成
如果您需要连接到 mac-messages-mcp 从Docker容器中，您需要使用 mcp-proxy 用于将基于stdio的服务器桥接到HTTP的包。
此存储库还包括 Dockerfile 对于目录检查和容器构建：
docker build -t mac-messages-mcp .Messages.app自动化仅适用于macOS，无法在Linux容器中运行。容器主要用于MCP目录兼容性和装载数据的只读数据库实验。
安装说明
- 在macOS主机上安装mcp代理：
npm install -g mcp-proxy- 启动代理服务器：
# Using the published version
npx mcp-proxy uvx mac-messages-mcp --port 8000 --host 0.0.0.0
# Or using local development (if you encounter issues)
npx mcp-proxy uv run python -m mac_messages_mcp.server --port 8000 --host 0.0.0.0- 从Docker连接：
您的Docker容器现在可以连接到：
- 网址：
http://host.docker.internal:8000/mcp（在macOS/Windows上） - 网址：
http://:8000/mcp（在Linux上）
- Docker编写示例：
version: '3.8'
services:
your-app:
image: your-image
environment:
MCP_MESSAGES_URL: "http://host.docker.internal:8000/mcp"
extra_hosts:
- "host.docker.internal:host-gateway" # For Linux hosts- 运行多个MCP服务器：
# Terminal 1 - Messages MCP on port 8001
npx mcp-proxy uvx mac-messages-mcp --port 8001 --host 0.0.0.0
# Terminal 2 - Another MCP server on port 8002
npx mcp-proxy uvx another-mcp-server --port 8002 --host 0.0.0.0注： 绑定到 0.0.0.0 将服务暴露给所有网络接口。在生产环境中，考虑使用更严格的主机绑定并添加身份验证。
选项1：从PyPI安装
uv pip install mac-messages-mcp选项2：从源代码安装
# Clone the repository
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp
# Install dependencies
uv install -e .用法
智能消息传递
Mac Messages MCP自动处理跨不同平台的消息传递：
- iMessage用户 （iPhone、iPad、Mac）：通过iMessage发送的消息
- Android用户：消息自动回退到SMS/RCS
- 混合团体：为每个收件人选择最佳交付方式
# Send to iPhone user - uses iMessage
send_message("+1234567890", "Hey! This goes via iMessage")
# Send to Android user - automatically uses SMS
send_message("+1987654321", "Hey! This goes via SMS")
# Check delivery method before sending
check_imessage_availability("+1234567890") # Returns availability status作为一个模块
from mac_messages_mcp import get_recent_messages, send_message
# Get recent messages
messages = get_recent_messages(hours=48)
print(messages)
# Send a message (automatically chooses iMessage or SMS)
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result) # Shows whether sent via iMessage or SMS作为命令行工具
# Run the MCP server directly
mac-messages-mcp发展
版本控制
此项目使用语义版本控制。看 版本.md 有关版本控制系统如何工作以及如何发布新版本的详细信息。
要升级版本，请执行以下操作：
python scripts/bump_version.py [patch|minor|major]安全说明
此应用程序直接访问包含个人通信的Messages数据库。请负责任地使用它，并确保您拥有适当的权限。
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。
