lane-mac-mcp

Un servidor MCP de iMessage de solo lectura + CLI para macOS. Un único archivo auditable, sin capacidad de envío.

Claude (a través de MCP) o tú (a través de la CLI) pueden listar conversaciones, leer un chat y buscar en el historial de mensajes — y nada más. Solo lectura por construcción: v1 no contiene ningún código de envío. Todo el acceso a datos se delega en el /usr/bin/sqlite3 de Apple con -json -readonly contra ~/Library/Messages/chat.db; los nombres de contacto provienen de consultas de solo lectura contra las bases de datos locales de AddressBook.

Restricciones de diseño

Todo el servidor es server.ts (~600 líneas, comentarios incluidos) para que pueda auditarse de principio a fin — el archivo auditado es el archivo en ejecución, ya que Node ≥ 22.18 ejecuta TypeScript directamente con eliminación nativa de tipos (sin paso de compilación, sin artefactos compilados). Hay exactamente dos dependencias, fijadas mediante package-lock.json: @modelcontextprotocol/sdk y zod. Sin importaciones de red, sin puertos abiertos — solo stdio JSON-RPC, lanzado como proceso hijo por Claude Desktop; las ejecuciones de la CLI son procesos de un solo uso. No hay demonio: Claude Desktop inicia y detiene el servidor con la aplicación (reinicia la aplicación para recargar el código).

Related MCP server: imessage-rich-search

Requisitos

macOS con Messages configurado, Node.js ≥ 22.18 y Acceso completo al disco para el proceso que ejecute el servidor: Terminal (o tu aplicación de terminal) para uso de la CLI, y Claude Desktop para uso de MCP. Concédelo en Ajustes del Sistema → Privacidad y seguridad → Acceso completo al disco y reinicia la aplicación. node server.ts doctor comprueba todo esto y te indica qué falta.

Configuración

git clone <this repo> && cd MacMCPServer
npm install          # installs the two pinned dependencies
node server.ts doctor

Luego añade el servidor al claude_desktop_config.json de Claude Desktop (Ajustes → Desarrollador → Editar configuración):

{
  "mcpServers": {
    "lane-mac": {
      "command": "node",
      "args": ["/Users/you/Desktop/MacMCPServer/server.ts"]
    }
  }
}

Reinicia Claude Desktop. Aparecen tres herramientas: list_chats, read_chat, search_messages.

Uso de la CLI

node server.ts chats                                   # recent chats, names resolved
node server.ts chats --search "mom" --limit 5
node server.ts chats --awaiting-reply-only             # threads where the last word wasn't yours
node server.ts read "Martha" --limit 100               # fuzzy name; ambiguous → candidates
node server.ts read 42 --start-date 2024-01-01 --end-date 2024-06-30 --include-reactions
node server.ts search "dinner" --from "martha"         # last 30 days by default
node server.ts search "dinner" --start-date 2015-01-01 --deep   # older history + rich-text decode
node server.ts doctor

La salida es JSON. search cubre message.text con SQL LIKE; --deep además decodifica mensajes cuyo texto reside solo en el blob attributedBody (escaneo acotado, más lento). Las reacciones Tapback se excluyen en todas partes salvo con --include-reactions.

Peculiaridades de Apple gestionadas

Las marcas de tiempo son nanosegundos desde 2001-01-01 (segundos en filas muy antiguas) — ambas se convierten. El texto de los mensajes suele residir en el blob typedstream attributedBody en lugar de en message.text; se decodifica en JS con la heurística conocida de NSString. Los nombres de contacto se emparejan por teléfono normalizado de los últimos 10 dígitos o correo electrónico en minúsculas en todas las fuentes de AddressBook, degradando con elegancia a números brutos cuando los contactos no se pueden leer.

Postura de privacidad y seguridad

El servidor solo puede leer. Abre las bases de datos con la bandera -readonly de sqlite3, no contiene ninguna ruta de código que escriba en ninguna base de datos ni envíe ningún mensaje, no realiza conexiones de red y no escucha en ningún puerto. La entrada del usuario se escapa en literales de cadena SQL (duplicando '') y los valores numéricos se validan. doctor imprime solo recuentos de filas, nunca contenido de mensajes. Existen anulaciones de entorno (CHAT_DB_PATH, SQLITE_BIN, ADDRESSBOOK_DIR) para que las pruebas nunca toquen datos reales.

Pruebas

npm test

Las pruebas de caja negra generan un chat.db sintético y un fixture de AddressBook (incluyendo un mensaje solo con attributedBody, un tapback y un hilo entrante sin responder) y manejan la CLI real y la interfaz stdio real de MCP como procesos hijos. El desarrollo nunca toca datos reales.

Hoja de ruta (más adelante, no en v1)

Pulido del enriquecimiento de contactos → lectura de Notas mediante osascript → envíos controlados por una variable de entorno SEND_ENABLED más aprobación por llamada.