Skip to main content
Glama
Apple Messages MCP

Apple Messages MCP

Apple Messages MCP

Lee y busca tus conversaciones de iMessage, SMS y RCS desde Claude, en macOS.

Complemento de claude-connector-apple-mail y claude-connector-apple-reminders.

Estado: la lectura y la búsqueda son sólidas. El envío funciona, pero no está probado en un envío real — la llamada de scripting está implementada y su sintaxis verificada, pero Apple ha roto send antes, así que trata el primer envío real como una prueba. Ver Envío de mensajes.

Herramientas

Tool

Description

get_stats

Totales, recuento de no leídos, desglose por servicio (iMessage/SMS/RCS), rango de fechas

list_chats

Conversaciones, las más recientes primero, con participantes y una vista previa

get_chat_messages

Mensajes de una conversación, de más antiguo a más reciente, paginados

search_messages

Búsqueda de subcadenas en todo el historial, filtrada por chat, remitente y rango de fechas

get_message

Un mensaje completo, con adjuntos y marcas de tiempo de entrega

get_attachment

Bytes del adjunto, codificados en base64

refresh_search_index

Calienta o reconstruye el índice de búsqueda local

compose_message

Abre Messages con el texto prellenado — tú pulsas enviar

send_message

Envía a una conversación existente; entrega inmediatamente

Related MCP server: iMessage MCP Server

Requisitos

  • macOS 13 Ventura o posterior. RCS requiere macOS 26 o posterior.

  • Acceso total al disco para la app de Claude — necesario para la lectura.

  • Permiso de Automatización para Messages — necesario para el envío y para los nombres de contacto. macOS solicita este permiso automáticamente.

Cómo otorgar Acceso total al disco

  1. Ajustes del Sistema → Privacidad y Seguridad → Acceso total al disco

  2. Activa Claude (añade /Applications/Claude.app con + si no aparece en la lista)

  3. Sal y vuelve a abrir Claude. macOS guarda en caché este permiso al iniciar el proceso, por lo que el reinicio es obligatorio: la extensión seguirá fallando sin él.

Por qué esto necesita Acceso total al disco cuando Apple Mail no

La extensión de Apple Mail se comunica con Mail.app enteramente mediante scripting, por lo que no necesita permisos especiales. Messages no puede funcionar de esa manera.

El diccionario de AppleScript de Messages expone exactamente cuatro clases — account, chat, participant, file transfer — y ninguna clase de mensaje. Verificado en macOS 26.5.2:

$ osascript -e 'tell application "Messages" to get every text message of first chat'
syntax error: Expected "from", etc. but found identifier. (-2741)

Los chats y los participantes se enumeran sin problema; los cuerpos de los mensajes simplemente no están expuestos. Así que la única vía de lectura es SQLite sobre ~/Library/Messages/chat.db, que está protegido por TCC. A diferencia de la Automatización, el Acceso total al disco no puede solicitarse mediante programación: el usuario debe concederlo manualmente.

Por lo tanto, la extensión utiliza ambos permisos para distintas tareas:

Ámbito

Mecanismo

Permiso

Messages, chats, búsqueda, adjuntos

SQLite sobre chat.db

Acceso total al disco

Nombres de contacto para identificadores sin procesar

Scripting de Messages

Automatización

Envío

Scripting de Messages (send)

Automatización

Ventana de redacción, prellenada

Esquema de URL imessage: / sms:

ninguno

Los nombres de contacto provienen de la clase participant de Messages (full name), que lee la tarjeta de Contactos del usuario. Esto evita la base de datos de AddressBook, protegida por separado: si se deniega la Automatización, los identificadores se muestran simplemente como números sin procesar.

Notas de implementación

attributedBody. Desde Ventura, message.text es frecuentemente NULL y el cuerpo vive en message.attributedBody como un typedstream de Apple — el formato heredado de NSArchiver, que plistlib no puede leer. typedstream.py lo decodifica en Python puro, por lo que el paquete no necesita dependencia de PyObjC. Se ancla en el nombre de clase NSString/NSMutableString y lee la carga útil UTF-8 con prefijo de longitud después del marcador de tipo +. La decodificación es total: un cuerpo no decodificable produce None en lugar de hacer fallar la consulta.

Marcas de tiempo. message.date es la época de Apple (2001-01-01), en segundos antes de macOS 13 y en nanosegundos desde entonces. Ambos casos se detectan y se manejan.

Búsqueda. chat.db no incluye ningún índice de texto, y la mayoría de los cuerpos viven solo en attributedBody, donde SQL no puede verlos. Esa combinación es más problemática de lo que parece.

La primera implementación ampliaba su predicado a m.text LIKE ? OR m.attributedBody IS NOT NULL y volvía a filtrar el texto decodificado en Python. Como esa segunda cláusula es verdadera para casi todas las filas modernas, el LIMIT de la consulta truncaba el escaneo a los últimos cientos de mensajes antes de que el filtro de Python llegara a ejecutarse, por lo que cualquier coincidencia más antigua desaparecía silenciosamente. Una búsqueda de un mensaje real devolvía cero resultados en lugar de ser lenta. En un historial de 916 MB, eso significaba que la búsqueda cubría efectivamente solo los últimos días.

La solución es decodificar una sola vez en lugar de hacerlo por consulta. index.py replica los cuerpos decodificados y convertidos a minúsculas (casefold) en ~/Library/Caches/apple-messages-mcp/search-index.db, contra el que las búsquedas hacen join — de modo que la coincidencia, los filtros, el orden y el LIMIT se aplican al historial completo en SQL. El espejo es:

  • Incremental. Los mensajes nuevos se encuentran mediante una marca de agua message.ROWID. Las ediciones y las cancelaciones de envío reutilizan un ROWID existente, por lo que cada actualización también examina las 2000 filas más recientes — pero solo aquellas con date_edited establecido o con ambas columnas de cuerpo ahora NULL, ya que volver a decodificar 2000 blobs en cada búsqueda es un trabajo real que casi nunca encuentra nada. Una edición que Messages no haya marcado de algún modo, o una más antigua que esa ventana, necesita refresh_search_index(rebuild=True). Mejorar el decodificador de attributedBody también justifica una reconstrucción; aumentar SCHEMA_VERSION fuerza una.

  • Solo con casefold, y nada más. El texto mostrado sigue viniendo de chat.db, por lo que el espejo es puramente un oráculo de coincidencias. Almacenar str.casefold() reduce su tamaño a la mitad y hace que la coincidencia sin distinción de mayúsculas sea correcta para texto no ASCII — el LIKE de SQLite solo pliega mayúsculas para ASCII.

  • Desechable. Vive en ~/Library/Caches y se reconstruye si se elimina. Nada de esto escribe en chat.db.

No es FTS5, a pesar del plan anterior: FTS5 coincide con tokens completos, por lo que MATCH 'dentist' nunca encuentra "mydentist", lo cual es más restrictivo que la semántica de subcadena que documenta search_messages. Un escaneo de subcadenas sobre texto compacto con casefold ya es rápido, así que FTS5 habría duplicado el índice para una semántica que no podemos usar. Añadirlo más adelante es un cambio contenido si alguna consulta llegara a ir lenta.

Solo lectura y sin bloqueos. Las conexiones se abren con mode=ro y ninguna sentencia muta la base de datos. Si SQLite no puede abrir el WAL en vivo en modo solo lectura, recurre a una copia instantánea privada para que una instancia en ejecución de Messages.app nunca se vea afectada.

Tapbacks, ediciones, respuestas. Las reacciones se decodifican desde associated_message_type (2000–2007, con el rango 3000 como sus eliminaciones), las respuestas en hilo desde thread_originator_guid, y las ediciones desde date_edited.

Envío de mensajes

Messages no tiene objeto de borrador, por lo que no existe un análogo exacto del diseño de borrador primero de la extensión de Mail. Por lo tanto, la vía de escritura se presenta en dos niveles, y deliberadamente no son equivalentes.

compose_message — el valor seguro por defecto. Abre Messages con el destinatario y el cuerpo prellenados mediante el esquema de URL imessage: / sms:, y se detiene. Una persona lo lee y pulsa enviar, así que nada sale de la máquina por orden de Claude. Esta es también la única forma de iniciar una conversación nueva. No necesita ningún permiso.

send_message — entrega inmediatamente. Utiliza el send de la interfaz de scripting, y no se puede deshacer. Toma un chat_id en lugar de un número de teléfono, lo cual no es una limitación sino el objetivo: el diccionario acepta tanto un participant como un chat, y dirigirse a un chat existente por GUID permite que Messages elija el transporte (iMessage / SMS / RCS) en lugar de que quien llama adivine y envíe silenciosamente un SMS a alguien que está en iMessage. También requiere confirm=True, puramente como protección contra una activación casual.

Qué está verificado y qué no

Confirmado en macOS 26.5.2 — el diccionario expone

send : direct-parameter (file | text), to: (participant | chat)

la enumeración service type es SMS, iMessage, RCS, chat tiene una propiedad id GUID para dirigirse a él, y el AppleScript generado compila.

No confirmado: que un envío real realmente entregue. Apple ha roto el send de AppleScript antes, y su presencia en el diccionario nunca ha sido prueba de que funcione. Nada en el conjunto de pruebas entrega un mensaje, así que el primer envío real es el experimento. Si falla, shortcuts run con una acción "Enviar mensaje" es la alternativa que vale la pena probar a continuación.

El texto del mensaje llega a AppleScript como un argumento de osascript (on run argv) en lugar de ser interpolado en el código fuente del script, por lo que un cuerpo que contenga una comilla doble es inerte en lugar de un error de sintaxis o una inyección.

El envío de adjuntos no está conectado, aunque el parámetro directo file significa que está al alcance.

Desarrollo

python3 tests/test_db.py       # SQL, decoder, and search-index tests
python3 tests/test_send.py     # compose URLs, send guards, argv safety
python3 tools/probe_schema.py  # verify the real chat.db (needs Full Disk Access)
./build.sh                     # test, validate manifest, pack the .mcpb

tests/test_db.py crea bases de datos desechables con el esquema real, por lo que el SQL puede validarse sin Acceso total al disco ni un historial de mensajes real. Una de ellas entierra una coincidencia bajo 3000 mensajes más recientes, que es la prueba de regresión para el error de búsqueda truncada descrito anteriormente.

tests/test_send.py nunca envía nada ni abre una ventana: cubre el constructor de URL, las cláusulas de protección y el argv exacto de osascript — por lo que es seguro en cualquier lugar y, en consecuencia, no puede decirte si el send de Apple funciona.

Ninguna de las dos suites toca el índice de búsqueda real; ambas inyectan uno temporal.

Licencia

MIT

Available Tools

9 tools
compose_messageA

Open Messages with a recipient and text prefilled, WITHOUT sending.

This is the safe way to write a message: it puts the text in front of the user in Messages and stops, so they read it and press send themselves. Prefer it over send_message, and use it whenever the conversation does not exist yet — send_message can only reply to an existing one.

Args: handle: Recipient phone number or email, e.g. "+15551234567". body: Text to prefill. May be empty to just open the conversation. service: "imessage" or "sms" — which transport Messages preselects.

Inputs: handle (required), body, service. Returns: A compose window was opened; nothing was sent.

get_attachmentA

Retrieve an attachment's bytes, base64-encoded.

Args: attachment_id: Attachment id from get_message.

Inputs: attachment_id (required). Returns: size, filename, mime_type, data_base64

get_chat_messagesA

Read messages from one conversation, returned oldest-first.

In Claude the result renders as an inline card, so don't repeat its contents in your reply — a one-line summary or the answer to the user's question is enough.

Args: chat_id: Conversation id from list_chats. limit: Maximum messages to return (default 50). before_id: Return messages older than this message id, to page back through history.

Inputs: chat_id (required), limit, before_id. Returns: result

get_messageA

Read one message in full, including attachments and delivery times.

In Claude the result renders as an inline card, so don't repeat its contents in your reply — a one-line summary or the answer to the user's question is enough.

Args: message_id: Message id from search_messages or get_chat_messages.

Inputs: message_id (required). Returns: id, date, guid, text, +15 more

get_statsA

Overview of the Messages database: message and chat totals, unread count, attachment count, a per-service breakdown (iMessage / SMS / RCS), and the date range covered.

Inputs: no named parameters. Returns: by_service, attachments, group_chats, total_chats, +5 more

list_chatsA

List conversations, most recently active first.

In Claude the result renders as an inline card, so don't repeat its contents in your reply — a one-line summary or the answer to the user's question is enough.

Args: limit: Maximum conversations to return (default 30). offset: Conversations to skip, for paging through the list.

Inputs: limit, offset. Returns: result

refresh_search_indexA

Update the local search index, and report on it.

search_messages keeps this current on its own, so calling this is optional. It is useful for warming the index deliberately — the first build on a large history decodes every message and takes a while — and for forcing a full rebuild.

Args: rebuild: Discard the index and decode every message again. Needed only to pick up edits to messages older than the recent-edit window.

Inputs: rebuild. Returns: State of the local search mirror (see index.py).

search_messagesA

Search message bodies across every conversation, over all history.

Backed by a local index of decoded message bodies, which is brought up to date automatically. The first search on a large history has to build that index and may take a while; later searches are fast.

In Claude the result renders as an inline card, so don't repeat its contents in your reply — a one-line summary or the answer to the user's question is enough.

Args: query: Text to look for (case-insensitive substring match). Leave it out to search on the filters alone — chat_id plus a date range with no search term reads one conversation newest-first. limit: Maximum messages to return (default 30). chat_id: Restrict to one conversation from list_chats. from_me: True for only messages you sent, False for only received. after: Only messages at or after this time. before: Only messages at or before this time.

Inputs: after, limit, query, before, +2 more. Returns: query, total, messages, truncated

send_messageA

Send a message to an existing conversation. This delivers immediately.

IRREVERSIBLE — the message goes out as soon as this runs, and scripting cannot unsend it. Confirm the exact recipient and wording with the user before calling, and pass confirm=True to acknowledge that. If they have not clearly asked for it to be sent, use compose_message instead and let them press send.

Messages picks the transport (iMessage, SMS, or RCS) for the conversation itself, which is why this addresses a chat rather than a raw handle. To start a new conversation, use compose_message.

Args: chat_id: Conversation id from list_chats. body: Text to send. confirm: Must be True. A guard against sending by accident.

Inputs: body (required), chat_id (required), confirm. Returns: A message was actually delivered.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool has a clear primary purpose: listing chats, reading messages, single-message lookup, attachments, stats, compose, send, and index refresh are all distinct. The only mild overlap is between get_chat_messages and search_messages when search is given a chat_id with no query term, but the descriptions explicitly clarify this boundary.

    Naming Consistency5/5

    All tools use snake_case with a verb_noun shape (list_chats, get_message, send_message, compose_message, search_messages, refresh_search_index). No mixed conventions or vague standalone verbs.

    Tool Count5/5

    Nine tools is well-scoped for a Messages client: a compact read/search surface plus the two write paths (compose/send) and one maintenance operation. Nothing feels redundant or missing by count.

    Completeness4/5

    Core lifecycle is covered: discover chats, read messages, search, fetch attachments, send and draft messages, plus stats and index maintenance. Minor gaps remain (e.g. group-chat creation or participant management, reactions, marking read), but agents can work around them.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to send and read iMessages on macOS, with smart contact lookup, message history retrieval, and cross-conversation search using natural language commands.
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to read and search through iMessage, SMS, and RCS conversations, including mixed-protocol group chats with Android users. It decodes binary message data from the macOS Messages database to provide a comprehensive view of message history.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to send and read iMessages on macOS, with human approval required for sending and no auto-replies.
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Connects Claude Desktop to iMessage on macOS, enabling reading conversations, searching messages, sending texts, and managing attachments.
      7
      8 npm
      MIT