Jons MCP Imessage

jons mcp信息

用于在macOS上查询和发送iMessage的本地MCP服务器。

此FastMCP服务器通过模型上下文协议（MCP）公开工具，使AI助手能够读取您的iMessage历史记录并发送消息。

需求

• macOS（在Tahoe 26.x上测试，应适用于最新版本）
• Python 3.10+
• Messages.app（用于发送消息）

所需权限

此服务器需要特定的macOS权限才能运行。 权限问题是问题最常见的原因。

全磁盘访问（阅读邮件时需要）

运行此服务器的应用程序需要完全磁盘访问权限才能读取 ~/Library/Messages/chat.db.

要授予全磁盘访问权限，请执行以下操作：

1. 打开 系统设置 （或旧版macOS上的系统首选项）
2. 导航到 隐私和安全 → 全磁盘访问
3. 如果需要，单击锁图标并进行身份验证
4. 点击 + 按钮
5. 添加相应的应用程序：

- 如果使用克劳德桌面：添加 Claude.app （通常在/应用程序中） - 如果从终端运行：添加您的终端应用程序（例如。， Terminal.app, iTerm.app, Zed.app) - 如果通过其他应用程序运行：添加该特定应用程序

1. 授予访问权限后重新启动应用程序

如何验证： 跑 check_permissions 工具-它将报告数据库访问是否正常。

自动化权限（发送消息时需要）

要通过AppleScript发送消息，应用程序需要控制messages.app的权限。

此权限会自动提示 第一次尝试发送消息时。单击“确定”以允许。

要手动授予或验证，请执行以下操作：

1. 打开 系统设置 → 隐私和安全 → 自动化
2. 查找您的应用程序（终端、克劳德桌面等）
3. 确保 消息 已检查

联系人权限（可选-用于联系人姓名扩展）

服务器可以使用您的联系人应用程序中的联系人姓名来丰富消息响应。这是 可选的 -没有它，所有功能都能正常工作，但你会看到电话号码/电子邮件，而不是名字。

要启用联系人姓名丰富功能，请执行以下操作：

1. 打开 系统设置 （或旧版macOS上的系统首选项）
2. 导航到 隐私和安全 → 联系人
3. 如果需要，单击锁图标并进行身份验证
4. 点击 + 按钮
5. 添加相应的应用程序：

- 如果使用克劳德桌面：添加 Claude.app （通常在/应用程序中） - 如果从终端运行：添加您的终端应用程序（例如。， Terminal.app, iTerm.app)

1. 授予访问权限后重新启动应用程序

您通过联系人权限获得的内容：

• 消息响应包括 contact_name 字段（例如，“约翰·史密斯”，而不仅仅是“+15551234567”）
• 对话回复包括 participant_names 领域
• lookup_contact 该工具可用于显式联系人查找

未经联系人许可：

• 联系人姓名字段将为 null
• lookup_contact 返回错误消息
• 所有其他功能正常工作（优雅降级）

安装

# Clone the repository
git clone 
cd jons-mcp-imessage

# Install with uv
uv pip install -e .

运行服务器

uv run jons-mcp-imessage

添加到克劳德代码

# Register the MCP server with Claude Code
claude mcp add jons-mcp-imessage -- uv run --directory /path/to/jons-mcp-imessage jons-mcp-imessage

添加到Claude桌面

将以下内容添加到您的Claude Desktop配置文件中：

地点： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jons-mcp-imessage": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jons-mcp-imessage",
        "jons-mcp-imessage"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

笔记：

• 替换 /path/to/jons-mcp-imessage 此存储库的实际路径
• 替换 sk-your-openai-api-key 使用OpenAI API密钥（语义搜索所需）
• 如果你没有OpenAI密钥，省略 env 完全部分-关键字搜索仍然有效
• 修改配置后重新启动Claude Desktop

搜索功能

搜索系统结合了两种强大的搜索方法：

关键字搜索（FTS5）

使用SQLite FTS5进行全文搜索，BM25排名。支持：

• 短语搜索： "exact phrase"
• 前缀匹配： word*
• 接近： word1 NEAR word2
• 布尔值： word1 AND word2, word1 OR word2, NOT word

语义搜索

使用OpenAI嵌入的人工智能搜索可以找到概念上相似的消息，即使确切的关键字不匹配。

设置

1. 基本设置 （仅限关键字搜索）：开箱即用
2. 完整设置 （混合搜索）：设置您的OpenAI API密钥：

   export OPENAI_API_KEY=your-api-key

搜索模式

• hybrid （默认）：使用RRF组合关键字+语义结果
• keyword：仅限FTS5（不需要API密钥）
• semantic：仅嵌入相似性（需要API密钥）

索引管理

搜索索引与iMessage的chat.db分开存储在： ~/.local/share/jons-mcp-imessage/search_index.db

可用工具：

• search_index_status -检查索引运行状况和同步状态
• rebuild_search_index -完全重新索引（出现问题时使用）

故障排除

可用工具

读取消息

发送消息

send_message限制

重要提示： 这 send_message 该工具存在明显的局限性：

1. 仅限现有对话：只能发送给您以前发过消息的联系人。新联系人需要先在Messages.app中手动启动对话。

1. 无交货确认：当消息传递给Messages.app时，该工具报告成功，但无法确认实际交付。在以下情况下，消息可能会自动失败：

- 收件人已阻止您 - 电话号码/电子邮件无效 - 出现网络问题

1. Messages.app必须正在运行：如果Messages.app未运行，该工具将失败，并出现“Messages not running”错误。

1. 服务检测：默认情况下，会先尝试iMessage。使用 service="SMS" 强制非iMessage联系人发送短信。

示例用法

# Check if permissions are configured correctly
check_permissions()

# List your 10 most recent conversations
list_conversations(limit=10)

# Get messages from a specific contact
get_conversation_messages(contact="+15551234567", limit=20)

# Search for messages containing specific text
search_messages(query="dinner plans", sender="+15551234567")

# Get context around a specific message (5 messages before and after)
get_message_context(rowid=12345, before=5, after=5)

# Send a message (to existing conversation only)
send_message(recipient="+15551234567", message="Hello!")

故障排除

“权限被拒绝”或“无法读取数据库”

原因： 未授予完整磁盘访问权限。

修复： 按照上面的全磁盘访问说明进行操作。确保：

• 授予对正确应用程序（实际运行服务器的应用程序）的访问权限
• 授予访问权限后重新启动应用程序

“消息未运行（-600）”

原因： Messages.app未运行。

修复： 发送消息前打开Messages.app。

“不允许发送Apple事件（-1743）”

原因： 未授予自动化权限。

修复：

1. 转到系统设置→ 隐私和安全→ 自动化
2. 找到您的应用程序并启用消息访问
3. 如果未列出，请尝试再次发送消息以触发权限提示

“无法获取好友id”或“仅限现有对话”

原因： 尝试给一个你以前没有发过消息的联系人发消息。

修复： 请先在Messages.app中手动与此联系人开始对话，然后重试。

消息显示为空或“（非短信）”

原因： 该消息仅包含附件（图像、视频）或是系统消息（如“重命名组”）。

注： 这是预期的行为。服务器仅提取文本内容。

保密考虑

此服务器访问您的本地iMessage数据库，也可以访问您的联系人数据库。请注意：

• 所有消息历史记录均可访问：服务器可以读取本地存储的所有消息
• 联系人信息已公开：电话号码和电子邮件地址可见
• 引用附件：包括附件（照片、视频）的文件路径
• 无云访问：只能访问本地存储的消息（不包括仅在iCloud上的消息）

联系人姓名隐私

如果您授予联系人权限：

• 联系人姓名来自您的联系人应用程序：服务器读取您的个人联系人列表以丰富消息响应
• 名称未存储：联系人姓名在查询时解析，不存储在任何数据库或搜索索引中
• 名称仅缓存在内存中：服务器在首次使用时将所有联系人加载到内存中，重新启动时清除缓存
• 读取所有联系人数据库：包括主联系人数据库以及任何源数据库（iCloud、CardDAV等）

在授予AI助手访问此服务器的权限时，请务必谨慎。

发展

设置

# Install with dev dependencies
uv pip install -e ".[dev]"

运行测试

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Run a specific test file
uv run pytest tests/test_parser.py

代码质量

# Type check
uv run mypy src/jons_mcp_imessage

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests

项目结构

jons-mcp-imessage/
├── src/
│   └── jons_mcp_imessage/
│       ├── __init__.py          # Package exports
│       ├── constants.py         # Configuration constants
│       ├── exceptions.py        # Custom exceptions
│       ├── utils.py             # Utility functions
│       ├── server.py            # FastMCP server setup
│       ├── db/
│       │   ├── __init__.py      # Database module exports
│       │   ├── connection.py    # SQLite connection management
│       │   ├── models.py        # Pydantic data models
│       │   ├── parser.py        # attributedBody binary parser
│       │   └── queries.py       # Query helpers and utilities
│       └── tools/
│           ├── __init__.py      # Tool exports
│           ├── health.py        # Permission checking
│           ├── contacts.py      # Contact search
│           ├── conversations.py # Conversation tools
│           ├── messages.py      # Message tools
│           └── send.py          # Message sending
├── tests/
│   ├── test_parser.py           # attributedBody parser tests
│   ├── test_db.py               # Database utility tests
│   └── test_send.py             # Send tool tests
├── docs/
│   └── IMESSAGE_DATABASE_FORMAT.md  # Database format documentation
├── pyproject.toml               # Project configuration
├── CLAUDE.md                    # AI assistant guidance
└── README.md                    # This file

许可证

麻省理工学院