Multimodal iMessage MCP

El servidor MCP de iMessage más completo para Claude. Lee conversaciones completas, busca mensajes, ve archivos adjuntos de imágenes, envía mensajes, busca contactos y reacciona a mensajes, todo desde Claude Desktop o Claude Code.

Por Qué Existe

Cada otra herramienta MCP de iMessage consulta la columna text en chat.db de Apple. ¿El problema? En macOS moderno (14+), el 93% de los mensajes se almacenan en attributedBody en lugar de text. Esas herramientas devuelven silenciosamente conversaciones vacías o incompletas.

Este servidor realiza ingeniería inversa del formato binario NSAttributedString de Apple para extraer el contenido real del mensaje, brindándote acceso a tu historial de mensajes completo.

Related MCP server: jons-mcp-imessage

Características

Multimodal: Claude Puede Ver Tus Fotos

Cuando usas get_attachment, las imágenes se devuelven como bloques de contenido base64 que Claude puede mirar realmente. Las fotos HEIC (predeterminado de iPhone) se convierten automáticamente a JPEG. Esto significa que Claude puede:

• Describir lo que hay en una foto que alguien te envió

• Leer texto/capturas de pantalla de imágenes

• Analizar contenido visual en tus conversaciones

Requisitos

• macOS (esto lee la base de datos local de iMessage)

• Node.js >= 18 y < 26. Se recomienda Node 24 LTS porque la dependencia SQLite nativa bloqueada no es compatible con Node 26.

• Acceso completo al disco concedido a tu aplicación de terminal (Configuración del Sistema > Privacidad y Seguridad > Acceso completo al disco). Esto cubre tanto la base de datos de iMessage como la base de datos de la Libreta de Direcciones utilizada para la resolución de nombres de contacto — no es necesario tener la aplicación Contactos abierta.

Instalación

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

Configuración

Claude Desktop

Agrega a tu ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

Importante: Usa la ruta completa a tu binario de Node.js (ej., /opt/homebrew/bin/node), no solo node. Las aplicaciones de escritorio de macOS no heredan el PATH de tu shell, y usar un comando node simple a menudo se resuelve a un Node del sistema más antiguo que causa fallos de módulos nativos.

Claude Code

Agrega a tu .mcp.json:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

En Claude Code, node normalmente se resuelve correctamente ya que hereda el entorno de tu shell.

Ejemplos de Uso

"Muéstrame mis mensajes recientes" — lee tus últimas conversaciones

"¿Qué me envió Mamá hoy por mensaje?" — resuelve "Mamá" a un número de teléfono a través de tu Libreta de Direcciones, obtiene la conversación

"Busca en mis mensajes 'confirmación de vuelo'" — búsqueda de texto completo en todos los mensajes

"Encuentra prospectos de divulgación de los últimos 7 días que respondieron y necesitan seguimiento" — devuelve candidatos de divulgación estructurados con etiquetas de riesgo

"Previsualiza este lote de 10 textos de seguimiento" — devuelve destinatarios exactos, mensajes, advertencias y un token de aprobación antes de que se envíe algo

"Muestra fallos de entrega recientes" — informa mensajes salientes que Mensajes marcó como fallidos o pendientes, incluyendo si un envío posterior de SMS/RCS recuperó el hilo

"Muéstrame la foto del mensaje 538516" — devuelve la imagen real para que Claude la vea y describa

"Envía 'Llego 10 min tarde' al +1234567890" — envía un iMessage (requiere confirmación)

Banderas de Versión

Las banderas de versión son opcionales a través del entorno del servidor MCP:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

Herramientas de Mutación

delete_messages acepta ROWIDs de mensajes exactos:

{ "message_ids": ["538516", "538517"] }

No requiere confirmación. Informa IDs eliminados, IDs faltantes, ubicación de la copia de seguridad y cualquier fila restante encontrada durante la verificación.

delete_threads es un flujo de lote exacto de dos pasos:

{ "chat_ids": [101, 102] }

La vista previa devuelve un approval_token para esa lista ordenada y los metadatos del hilo mostrados en la vista previa. Para eliminar, envía los mismos chat_ids ordenados, confirm: true y ese token:

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

Cambiar el orden, la lista o el token hace que la solicitud falle.

edit_message y undo_send_message son experimentales porque Mensajes no expone comandos AppleScript de primera clase para esas acciones. Abren la conversación, encuentran la burbuja saliente visible por fragmento de texto, usan el menú contextual y luego verifican el resultado. Están destinados a afectar el comportamiento real de Mensajes, no ediciones falsas de solo DB local.

Ajuste opcional:

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

Esto controla cuánto tiempo espera el MCP antes de verificar la base de datos local de Mensajes para la nueva fila saliente.

Cómo Funciona

La Solución attributedBody

La base de datos de iMessage de Apple (~/Library/Messages/chat.db) tiene dos columnas para el contenido del mensaje:

• text — la columna de texto plano heredada (usada por versiones anteriores de macOS)

• attributedBody — un blob NSAttributedString serializado (usado por macOS 14+)

En macOS moderno, Apple migró gradualmente el almacenamiento de mensajes a attributedBody para soportar texto enriquecido, menciones y formato. La columna text es cada vez más solo un respaldo heredado que a menudo es NULL.

Este servidor detecta mensajes con texto NULL y extrae el contenido de attributedBody analizando el formato binario NSTypedStream:

1. Encuentra el marcador NSString en el blob binario

2. Lee más allá de los bytes de encabezado de tipo (01 94 84 01 2b)

3. Decodifica el prefijo de longitud (un solo byte para mensajes cortos, varios bytes para los más largos)

4. Extrae la carga útil de texto UTF-8

Manejo de Archivos Adjuntos

Los archivos adjuntos de iMessage se almacenan en ~/Library/Messages/Attachments/ con rutas rastreadas en la tabla attachment. La herramienta get_attachment:

1. Consulta los metadatos del archivo adjunto para un ID de mensaje dado

2. Resuelve la ruta ~/Library/Messages/... a una ruta absoluta

3. Para JPEG/PNG/GIF/WebP: lee el archivo y devuelve el contenido de la imagen en base64

4. Para HEIC (predeterminado de iPhone): convierte a JPEG usando sips de macOS antes de devolverlo

5. Para otros archivos: devuelve metadatos y la ruta del archivo

Solución de Problemas

"No se pudo abrir la base de datos de iMessage" Concede Acceso completo al disco a tu aplicación de terminal: Configuración del Sistema > Privacidad y Seguridad > Acceso completo al disco.

La búsqueda de contactos no devuelve resultados La resolución de contactos lee las bases de datos SQLite de la Libreta de Direcciones de macOS directamente (no se necesita la aplicación Contactos). Asegúrate de que el Acceso completo al disco esté concedido. Si se acaba de agregar un contacto, reinicia el servidor MCP para actualizar la caché.

Fallo de módulo nativo / "NODE_MODULE_VERSION mismatch" Reconstruye las dependencias nativas: npm rebuild. Esto sucede cuando cambia la versión de tu Node.js. También asegúrate de que tu configuración de Claude Desktop use la ruta completa a node (ver Configuración arriba).

Faltan mensajes de una conversación Este es exactamente el error que este servidor soluciona. Asegúrate de estar ejecutando la última versión que incluye la extracción de attributedBody.

Licencia

MIT

Inicio Rápido TL;DR

npm install
node index.js

Luego añade el servidor a la configuración de tu cliente MCP y concede Acceso al disco completo a tu aplicación de terminal.

Cómo funciona (TL;DR)

• Lee la base de datos SQLite de iMessage de macOS

• Decodifica payloads modernos de attributedBody para el texto completo del mensaje

• Expone herramientas de conversación/búsqueda/adjuntos mediante MCP

• Utiliza AppleScript para acciones de envío/reacción de mensajes con confirmaciones explícitas

Copia rápida para LLM

Usa el botón de copiar en este bloque de código en GitHub.

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools