imessage-mcp

Un servidor MCP local que expone los datos de iMessage de tu Mac a Claude Desktop / Claude Code. Dos superficies:

1. ENVIAR mediante AppleScript → Messages.app

2. LEER mediante acceso directo y de solo lectura a SQLite en ~/Library/Messages/chat.db

Todo es local. Sin claves de API, sin llamadas de red.

Instalación

# 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

Permisos (requeridos)

Acceso total al disco — para que podamos leer chat.db

Configuración del sistema → Privacidad y seguridad → Acceso total al disco → activa el interruptor para:

• tu aplicación de terminal (ej. Terminal, iTerm2, Ghostty), Y

• Claude.app (si usas Claude Desktop)

Automatización — para que podamos controlar Messages.app

Configuración del sistema → Privacidad y seguridad → Automatización → despliega tu terminal / Claude.app y activa Messages.

Messages.app debe estar ejecutándose y con la sesión iniciada en iMessage.

Si falta un paso de permiso, el servidor mostrará un error con la ruta exacta de la configuración que debes abrir.

Configuración de Claude Desktop

Combínalo en ~/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"]
    }
  }
}

(La ruta absoluta al python del venv es la más segura; evita la ambigüedad de PATH. Reemplaza YOUR_USERNAME.)

Herramientas

Las fechas están en formato ISO8601 tanto de entrada como de salida. Internamente, Apple almacena message.date como nanosegundos desde el 01-01-2001 UTC; el servidor realiza la conversión en ambos sentidos.

Invariantes de seguridad

• chat.db se abre con sqlite3.connect("file:...chat.db?mode=ro", uri=True). Cualquier intento de escritura genera un sqlite3.OperationalError: attempt to write a readonly database.

• send_imessage pasa el destinatario / cuerpo / servicio como entradas de argv de osascript separadas — sin interpolación de shell, sin inyección.

• Los archivos adjuntos devuelven solo metadatos (nombre de archivo, mime_type, total_bytes). Los blobs nunca se leen.

Limitaciones

• No se admiten envíos programados / retrasados.

• Los mensajes enriquecidos / con hilos de respuesta pueden tener su texto almacenado en attributedBody (NSKeyedArchive). Hacemos el mejor esfuerzo para extraer el NSString incrustado; los mensajes con cargas útiles más exóticas (imágenes, toques, Apple Pay) mostrarán un body vacío pero con los metadatos correctos.

• Confirmación de entrega: send_imessage informa del éxito a partir del código de salida de osascript. Para verificar que el mensaje realmente se envió, llama a search_imessages o get_chat_messages unos segundos después.

• Esto es exclusivo de macOS y no funcionará en aplicaciones de la App Store en entorno aislado (sandboxed).

Desarrollo local

.venv/bin/pytest -q