金大哥 - mac_messages

article

README

🚀 macOS 消息 MCP 读写桥接器（Python 版）

这是一个 Python 桥接器，可通过 MCP（多上下文协议）与 macOS Messages 应用程序进行交互，实现消息的读取和发送等功能。

a-diagram-of-a-mac-computer-with-the-tex_FvvnmbaBTFeKy6F2GMlLqA_IfCBMgJARcia1WTH7FaqwA

✨ 主要特性

可读取 macOS Messages 应用程序的最近消息。
支持按联系人过滤消息。
能通过 iMessage 发送新消息。
可通过 API 访问消息。

🚀 快速开始

先决条件

macOS（已在 macOS 11+ 上测试运行）。
Python 3.10+。
uv 包管理器

安装 uv

如果你使用的是 Mac，可通过 Homebrew 安装 uv：

brew install uv

若不是 Mac 系统，请按照 uv 官网的安装说明进行操作。

⚠️ 重要提示

请在安装 uv 之前不要继续操作。

安装

全盘访问权限

此应用程序需要为你的终端或应用程序授予全盘访问权限，才能访问 Messages 数据库。设置步骤如下：

打开 系统偏好设置/设置 > 安全与隐私/隐私 > 全盘访问。
点击锁图标以允许更改。
在列表中添加你的终端应用程序（如 Terminal、iTerm2 等）或 Claude Desktop/Cursor。
授予权限后重新启动终端或应用程序。

集成

Claude Desktop 集成

转到 Claude > 设置 > 开发人员 > 编辑配置 > claude_desktop_config.json。
添加以下配置：

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

Cursor 集成

转到 Cursor Settings > MCP，并粘贴以下命令：

uvx mac-messages-mcp

⚠️ 重要提示

只能运行一个 MCP 服务器实例（无论是 Claude Desktop 还是 Cursor），不要同时运行两者。

安装选项

选项 1：从 PyPI 安装

uv pip install mac-messages-mcp

选项 2：从源代码安装

# 克隆仓库
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

# 安装依赖项
uv install -e .

💻 使用示例

基础用法

作为模块使用

from mac_messages_mcp import get_recent_messages, send_message

# 获取最近消息
messages = get_recent_messages(hours=48)
print(messages)

# 发送消息
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)

作为命令行工具使用

# 运行 MCP 服务器
mac-messages-mcp

📚 详细文档

开发

版本控制

此项目使用语义版本控制。有关版本控制系统如何工作以及如何发布新版本的详细信息，请参阅 VERSIONING.md。

要调整版本，可使用以下命令：

python scripts/bump_version.py [patch|minor|major]

安全注意事项

此应用程序直接访问 Messages 数据库，需妥善管理权限和数据安全。

附加说明

MCP 协议简介

MCP（多上下文协议）是一种用于在不同进程或服务之间通信的机制。在此项目中，我们使用 MCP 来桥接 Python 脚本与 macOS Messages 应用程序之间的交互。

支持的消息操作

目前支持以下消息相关操作：

获取最近消息
按联系人过滤消息
发送新消息

未来发展

未来计划添加更多功能，例如：

支持更多消息类型
提供图形用户界面
增强安全性与稳定性

贡献者

此项目由 carterlasalle 开发和维护。

📄 许可证

此项目采用 MIT 许可证。

mac_messages_mcp