iMessage MCP

Монорепозиторий Deno, содержащий пакеты для доступа к iMessage на macOS:

• @wyattjoh/imessage — Основная библиотека для доступа к базе данных iMessage в режиме только для чтения

• @wyattjoh/imessage-mcp — Сервер Model Context Protocol (MCP) для интеграции с LLM

Возможности

• Поиск сообщений по тексту, контакту или диапазону дат

• Получение последних сообщений

• Список всех чатов и диалогов

• Получение всех контактов/handles

• Получение сообщений из конкретных чатов

• Поиск контактов macOS по имени с сопоставлением с идентификатором handle из iMessage

Related MCP server: imessage-mcp

Требования

• macOS (iMessage доступен только в macOS)

• Deno 2.x или новее

• Доступ на чтение к ~/Library/Messages/chat.db или к пользовательской базе данных, указанной через IMESSAGE_DB_PATH

• Доступ на чтение к ~/Library/Application Support/AddressBook/ (для поиска контактов)

Пакеты

@wyattjoh/imessage

Основная библиотека для доступа к данным iMessage:

deno add @wyattjoh/imessage

import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";

const db = await openMessagesDatabase();
const results = await searchMessages(db, { query: "hello" });
db.close();

См. полную документацию

@wyattjoh/imessage-mcp

MCP-сервер для интеграции с LLM:

# Run directly from JSR
deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp

# Or install globally
deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp

Для интеграции с приложением Claude Desktop добавьте это в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}

Пользовательская база данных сообщений

Установите переменную IMESSAGE_DB_PATH, чтобы открыть базу данных SQLite в другом месте — например, периодически обновляемую копию chat.db:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env=IMESSAGE_DB_PATH",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ],
      "env": {
        "IMESSAGE_DB_PATH": "/tmp/imessage-snapshot.sqlite"
      }
    }
  }
}

Процессу требуется доступ на чтение к пользовательскому файлу. Если у Deno нет разрешения на чтение переменной IMESSAGE_DB_PATH или если переменная пуста или не задана, библиотека использует ~/Library/Messages/chat.db без запроса на доступ к окружению.

Вариант 2: Из исходного кода

1. Клонируйте этот репозиторий

2. Установите зависимости:

   deno cache src/index.ts

3. Запустите сервер:

   deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts
   # Or use the task:
   deno task start

Доступные инструменты

1. search_messages — Поиск сообщений с фильтрами

   • query (необязательно): текст для поиска

   • handle (необязательно): номер телефона или email для фильтрации

   • startDate (необязательно): строка даты и времени ISO для начальной даты

   • endDate (необязательно): строка даты и времени ISO для конечной даты

   • limit (необязательно): максимальное количество результатов (1-200, по умолчанию: 100)

   • offset (необязательно): смещение при постраничном выводе (по умолчанию: 0)

2. get_recent_messages — Получение последних сообщений

   • limit (необязательно): количество сообщений (1-100, по умолчанию: 20)

   • offset (необязательно): смещение при постраничном выводе (по умолчанию: 0)

3. get_chats — Список всех разговоров

   • limit (необязательно): количество чатов (1-200, по умолчанию: 50)

   • offset (необязательно): смещение при постраничном выводе (по умолчанию: 0)

4. get_handles — Получение всех контактов/handles

   • limit (необязательно): количество handles (1-200, по умолчанию: 100)

   • offset (необязательно): смещение при постраничном выводе (по умолчанию: 0)

5. get_messages_from_chat — Получение сообщений из конкретного чата

   • chatGuid (обязательно): GUID чата

   • limit (необязательно): количество сообщений (1-200, по умолчанию: 50)

   • offset (необязательно): смещение при постраничном выводе (по умолчанию: 0)

6. search_contacts — Поиск контактов macOS по имени и получение номеров телефонов

   • firstName (обязательно): имя для поиска (например, 'John')

   • lastName (необязательно): фамилия для поиска (например, 'Smith'). Если не указана, поиск выполняется по всем полям имени

   • limit (необязательно): максимальное количество результатов (1-200, по умолчанию: 50)

   • offset (необязательно): смещение при постраничном выводе (по умолчанию: 0)

   • Возвращает контактную информацию с номерами телефонов и email-адресами, которые можно использовать как handle

   • Выполняет поиск напрямую в базе данных macOS AddressBook для лучшей производительности и надёжности

Примеры пагинации

Все инструменты теперь поддерживают пагинацию с помощью параметров limit и offset и возвращают метаданные пагинации:

// Get first 20 recent messages
get_recent_messages({ limit: 20, offset: 0 });

// Get next 20 recent messages (page 2)
get_recent_messages({ limit: 20, offset: 20 });

// Get first 10 chats
get_chats({ limit: 10, offset: 0 });

// Get messages 51-100 from a specific chat
get_messages_from_chat({
  chatGuid: "iMessage;-;+15551234",
  limit: 50,
  offset: 50,
});

// Search with pagination
search_messages({
  query: "meeting",
  limit: 100,
  offset: 200,
});

// Search contacts with pagination
search_contacts({
  firstName: "John",
  lastName: "Smith",
  limit: 50,
  offset: 0,
});

Формат ответа с метаданными пагинации

Все инструменты с поддержкой пагинации теперь возвращают ответы в следующем формате:

{
  "data": [
    // Array of results (messages, chats, handles, etc.)
  ],
  "pagination": {
    "total": 1250, // Total number of results available
    "limit": 100, // Current page size
    "offset": 200, // Current offset
    "hasMore": true, // Whether there are more results to fetch
    "page": 3, // Current page number (1-indexed)
    "totalPages": 13 // Total number of pages
  }
}

Эти метаданные помогают вам:

• Узнать общее количество результатов, не загружая их все

• Определить, есть ли ещё страницы для загрузки (hasMore)

• Вычислить, на какой странице вы находитесь и сколько страниц существует

• Создавать правильные компоненты интерфейса пагинации

Замечания по безопасности

• Сервер работает с доступом только для чтения к базе данных iMessage

• Ни одно сообщение не может быть отправлено или изменено

• Сервер обращается только к локальным данным

Разработка

Это монорепозиторий с рабочим пространством Deno. Все команды, выполняемые из корня, влияют на все пакеты.

# Clone the repository
git clone https://github.com/wyattjoh/imessage-mcp.git
cd imessage-mcp

# Cache dependencies
deno cache packages/*/mod.ts

# Format all code
deno task fmt

# Lint all packages
deno task lint

# Type check all packages
deno task check

# Run tests
deno task test

# Run MCP server locally
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

# Publish packages (CI/CD)
deno publish

Работа с отдельными пакетами

# Work on @wyattjoh/imessage
cd packages/imessage
deno test --allow-read --allow-env --allow-ffi --allow-sys=homedir

# Work on @wyattjoh/imessage-mcp
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

Лицензия

MIT