iMessage MCP

Un monorepo de Deno que contiene paquetes para el acceso a iMessage en macOS:

• @wyattjoh/imessage - Biblioteca principal para el acceso de solo lectura a la base de datos de iMessage

• @wyattjoh/imessage-mcp - Servidor del Model Context Protocol (MCP) para la integración con LLM

Características

• Buscar mensajes por contenido de texto, contacto o rango de fechas

• Obtener mensajes recientes

• Listar todos los chats/conversaciones

• Obtener todos los contactos/handles

• Recuperar mensajes de chats específicos

• Buscar en los Contactos de macOS por nombre con correlación de ID de handle de iMessage

Related MCP server: imessage-mcp

Requisitos

• macOS (iMessage solo está disponible en macOS)

• Deno 2.x o posterior

• Acceso de lectura a ~/Library/Messages/chat.db, o a una base de datos personalizada configurada con IMESSAGE_DB_PATH

• Acceso de lectura a ~/Library/Application Support/AddressBook/ (para la búsqueda de contactos)

Paquetes

@wyattjoh/imessage

Biblioteca principal para acceder a los datos de iMessage:

deno add @wyattjoh/imessage

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

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

Ver documentación completa

@wyattjoh/imessage-mcp

Servidor MCP para la integración con 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

Para la integración con la aplicación Claude Desktop, añade esto a tu claude_desktop_config.json:

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

Base de datos de mensajes personalizada

Configura IMESSAGE_DB_PATH para abrir una base de datos SQLite de solo lectura en otra ubicación, como una copia actualizada periódicamente de 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"
      }
    }
  }
}

El proceso necesita acceso de lectura al archivo personalizado. Si Deno no tiene permiso para leer IMESSAGE_DB_PATH, o si la variable está vacía o sin definir, la biblioteca usa ~/Library/Messages/chat.db sin solicitar acceso al entorno.

Opción 2: Desde el código fuente

1. Clona este repositorio

2. Instala las dependencias:

   deno cache src/index.ts

3. Ejecuta el servidor:

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

Herramientas disponibles

1. search_messages - Buscar mensajes con filtros

   • query (opcional): Texto a buscar

   • handle (opcional): Número de teléfono o correo electrónico para filtrar

   • startDate (opcional): Cadena de fecha y hora ISO para la fecha de inicio

   • endDate (opcional): Cadena de fecha y hora ISO para la fecha de fin

   • limit (opcional): Resultados máximos (1-200, predeterminado: 100)

   • offset (opcional): Desplazamiento de paginación (predeterminado: 0)

2. get_recent_messages - Obtener los mensajes más recientes

   • limit (opcional): Número de mensajes (1-100, predeterminado: 20)

   • offset (opcional): Desplazamiento de paginación (predeterminado: 0)

3. get_chats - Listar todas las conversaciones

   • limit (opcional): Número de chats (1-200, predeterminado: 50)

   • offset (opcional): Desplazamiento de paginación (predeterminado: 0)

4. get_handles - Obtener todos los contactos/handles

   • limit (opcional): Número de handles (1-200, predeterminado: 100)

   • offset (opcional): Desplazamiento de paginación (predeterminado: 0)

5. get_messages_from_chat - Obtener mensajes de un chat específico

   • chatGuid (obligatorio): El GUID del chat

   • limit (opcional): Número de mensajes (1-200, predeterminado: 50)

   • offset (opcional): Desplazamiento de paginación (predeterminado: 0)

6. search_contacts - Buscar en los Contactos de macOS por nombre y obtener números de teléfono

   • firstName (obligatorio): Nombre a buscar (p. ej., 'John')

   • lastName (opcional): Apellido a buscar (p. ej., 'Smith'). Si se omite, busca en todos los campos de nombre

   • limit (opcional): Resultados máximos (1-200, predeterminado: 50)

   • offset (opcional): Desplazamiento de paginación (predeterminado: 0)

   • Devuelve información de contacto con números de teléfono y direcciones de correo electrónico que pueden usarse como parámetros de handle

   • Busca directamente en la base de datos de AddressBook de macOS para obtener un mejor rendimiento y fiabilidad

Ejemplos de paginación

Todas las herramientas ahora admiten paginación mediante los parámetros limit y offset y devuelven metadatos de paginación:

// 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,
});

Formato de respuesta con metadatos de paginación

Todas las herramientas paginadas ahora devuelven respuestas con este formato:

{
  "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
  }
}

Estos metadatos te ayudan a:

• Conocer el número total de resultados sin tener que obtenerlos todos

• Determinar si hay más páginas por obtener (hasMore)

• Calcular en qué página estás y cuántas páginas existen

• Crear componentes de interfaz de usuario de paginación adecuados

Notas de seguridad

• Este servidor se ejecuta con acceso de solo lectura a la base de datos de iMessage

• No se pueden enviar ni modificar mensajes

• El servidor solo accede a datos locales

Desarrollo

Este es un monorepo con workspace de Deno. Todos los comandos ejecutados desde la raíz afectan a todos los paquetes.

# 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

Trabajar en paquetes individuales

# 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

Licencia

MIT