imessage-mcp

Локальный MCP-сервер, который предоставляет данные iMessage вашего Mac для Claude Desktop / Claude Code. Два интерфейса:

1. ОТПРАВКА через AppleScript → Messages.app

2. ЧТЕНИЕ через прямой доступ только для чтения к SQLite-базе ~/Library/Messages/chat.db

Всё работает локально. Никаких API-ключей, никаких сетевых вызовов.

Установка

# 1. Clone / copy into ~/mcp-servers/imessage-mcp
cd ~/mcp-servers/imessage-mcp

# 2. Create a Python 3.11+ venv and install deps
python3.12 -m venv .venv
.venv/bin/pip install -e .

Related MCP server: imessage-mcp

Разрешения (обязательно)

Полный доступ к диску — чтобы мы могли читать chat.db

Системные настройки → Конфиденциальность и безопасность → Полный доступ к диску → включите для:

• вашего терминала (например, Terminal, iTerm2, Ghostty), И

• Claude.app (если используете Claude Desktop)

Автоматизация — чтобы мы могли управлять Messages.app

Системные настройки → Конфиденциальность и безопасность → Автоматизация → разверните ваш терминал / Claude.app и переключите Messages в положение ВКЛ.

Приложение Messages.app должно быть запущено и выполнено под вашей учетной записью iMessage.

Если какой-то шаг с разрешениями пропущен, сервер выдаст ошибку с точным путем к настройкам, которые нужно открыть.

Конфигурация Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/Users/YOUR_USERNAME/mcp-servers/imessage-mcp/.venv/bin/python",
      "args": ["-m", "imessage_mcp.server"]
    }
  }
}

(Абсолютный путь к python в venv — самый надежный вариант, он позволяет избежать неоднозначности PATH. Замените YOUR_USERNAME.)

Инструменты

Даты передаются в формате ISO8601. Внутри Apple хранит message.date как количество наносекунд с 2001-01-01 UTC; сервер выполняет преобразование в обе стороны.

Инварианты безопасности

• chat.db открывается с помощью sqlite3.connect("file:...chat.db?mode=ro", uri=True). Любая попытка записи вызывает sqlite3.OperationalError: attempt to write a readonly database.

• send_imessage передает получателя / текст / сервис как отдельные аргументы osascript — никакой интерполяции оболочки, никакой инъекции.

• Вложения возвращают только метаданные (имя файла, mime_type, размер в байтах). Бинарные данные (blobs) никогда не считываются.

Ограничения

• Запланированная / отложенная отправка не поддерживается.

• Текст сообщений с ответами или сложным форматированием может храниться в attributedBody (NSKeyedArchive). Мы стараемся извлечь встроенный NSString; сообщения с более экзотическими данными (изображения, реакции, Apple Pay) будут отображать пустое поле body, но корректные метаданные.

• Подтверждение доставки: send_imessage сообщает об успехе на основе кода выхода osascript. Чтобы убедиться, что сообщение действительно доставлено, вызовите search_imessages или get_chat_messages через несколько секунд.

• Это решение работает только на macOS и не будет работать в приложениях из App Store, работающих в «песочнице».

Локальная разработка

.venv/bin/pytest -q