Mac Messages MCP

Un puente en Python para interactuar con la aplicación Mensajes de macOS.

Documentación

Mac Messages MCP

Usa Claude, Codex, Cursor, VS Code o cualquier cliente MCP local para buscar, leer y enviar mensajes a través de la app Mensajes de macOS.

Mac Messages MCP se ejecuta localmente en tu Mac. Abre las bases de datos de Mensajes y Contactos en modo solo lectura, devuelve únicamente los datos que un cliente solicita y usa la automatización de Messages.app solo cuando el cliente llama explícitamente a la herramienta de envío.

[!IMPORTANT] Este servidor es solo para macOS. Leer mensajes requiere Acceso Total al Disco. Enviar requiere una Mac con sesión iniciada en Mensajes además del permiso para que la app que lo lanza automatice Mensajes.

Qué puede hacer

Leer mensajes recientes en todas las conversaciones o filtrar por contacto o chat grupal
Buscar texto de mensajes de forma aproximada en un rango de tiempo, incluyendo todo el historial disponible
Encontrar contactos por nombre aproximado y devolver números de teléfono listos para enviar
Listar chats grupales con nombre y usar sus IDs de chat para lecturas o envíos
Enviar iMessage, con respaldo SMS/RCS para destinatarios telefónicos elegibles
Verificar si un destinatario parece alcanzable por iMessage antes de enviar
Encontrar archivos adjuntos por fecha, remitente y tipo MIME
Devolver imágenes pequeñas en línea, convertir imágenes HEIC a PNG o devolver una ruta local para archivos más grandes y no imagen
Diagnosticar permisos de las bases de datos de Mensajes y Contactos desde el cliente MCP

Inicio rápido

1. Instalar `uv`

brew install uv

Confirma que el lanzador está disponible:

uvx --version

Se requiere Python 3.10 o superior. uvx puede aprovisionar un Python compatible e instala Mac Messages MCP en un entorno aislado, por lo que no necesitas crear un entorno virtual primero.

2. Otorgar permisos de macOS

Abre Configuración del Sistema → Privacidad y Seguridad → Acceso Total al Disco y habilita la app que lanzará el servidor MCP:

Claude Desktop, Cursor, VS Code o la app de escritorio de ChatGPT cuando esté configurada en esa app
Terminal, iTerm2, Ghostty u otra terminal cuando uses Claude Code o Codex CLI desde esa terminal

Sal y vuelve a abrir la app después de cambiar el Acceso Total al Disco. En la primera búsqueda de contacto o envío, macOS puede pedir por separado acceso a Contactos o permiso para controlar Mensajes. Permite esas solicitudes.

También asegúrate de que Messages.app esté abierta, con sesión iniciada y ya pueda enviar un mensaje normal.

3. Agregar el servidor a tu cliente MCP

El comando del servidor es el mismo en todas partes:

uvx mac-messages-mcp

Elige tu cliente a continuación.

Claude Desktop

Abre Claude → Configuración → Desarrollador → Editar Configuración y luego agrega:

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

Conserva cualquier otro servidor ya presente en claude_desktop_config.json, guarda el archivo y reinicia Claude Desktop.

Claude Desktop también admite extensiones instalables de .mcpb. Consulta Crear la extensión de Claude Desktop si quieres empaquetar este repositorio como una.

Claude Code

Agrégalo una vez a nivel de usuario para que esté disponible en todos los proyectos:

claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp

Verifícalo:

claude mcp get mac-messages

Dentro de Claude Code, ejecuta /mcp para inspeccionar la conexión y las herramientas.

Codex CLI, extensión IDE de Codex y app de escritorio de ChatGPT

Los clientes de Codex en la misma Mac comparten la configuración de MCP. Agrega el servidor con:

codex mcp add mac-messages -- uvx mac-messages-mcp

Luego verifícalo:

codex mcp list

También puedes agregarlo directamente a ~/.codex/config.toml:

[mcp_servers.mac-messages]
command = "uvx"
args = ["mac-messages-mcp"]

Reinicia la app de escritorio o la extensión del IDE después de cambiar la configuración. En Codex CLI, usa /mcp para ver el servidor activo.

Cursor

O abre Cursor Settings → Tools & MCP → New MCP Server y usa:

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

Reinicia el servidor desde la configuración de MCP de Cursor después de guardar.

VS Code / GitHub Copilot

Abre la Paleta de Comandos y ejecuta MCP: Add Server. Elige Command (stdio), ingresa uvx como comando, agrega mac-messages-mcp como argumento e instálalo globalmente.

O agrégalo desde una terminal:

code --add-mcp '{"name":"mac-messages","command":"uvx","args":["mac-messages-mcp"]}'

La entrada equivalente de mcp.json a nivel de usuario o espacio de trabajo es:

{
  "servers": {
    "mac-messages": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

[!NOTE] VS Code usa un objeto servers de nivel superior. Claude Desktop y Cursor usan mcpServers.

Otros clientes MCP stdio

Usa esta definición genérica de servidor:

{
  "command": "uvx",
  "args": ["mac-messages-mcp"]
}

Si un cliente GUI informa que no se puede encontrar uvx, ejecuta which uvx en Terminal y reemplaza "uvx" con la ruta absoluta devuelta. Homebrew comúnmente lo instala en /opt/homebrew/bin/uvx en Apple silicon y /usr/local/bin/uvx en Mac Intel.

4. Verificar la conexión

Pide a tu cliente que llame a tool_check_db_access y luego a tool_check_addressbook. Una vez que ambos tengan éxito, prueba indicaciones como:

Show me my messages from the last two hours.

Find messages from Carter about dinner in the last 30 days.

Find PDFs sent to me this month, but do not open any yet.

Find Jordan in my contacts and draft a message saying I am running 10 minutes
late. Do not send it until I confirm.

El primer lanzamiento de uvx puede tardar más mientras descarga y almacena en caché las dependencias de Python.

5. Opcional: configurar la región del número de teléfono

Los números de teléfono escritos en formato nacional (06 39 98 00 01, (415) 555-1234) deben expandirse a E.164 antes de poder coincidir con la base de datos de Mensajes, y esa expansión necesita saber a qué país pertenecen. El servidor lee la configuración regional de tu propia Mac para esto, por lo que en una Mac configurada correctamente no hay nada que hacer.

Configura MAC_MESSAGES_REGION a un código ISO 3166-1 alpha-2 cuando tus números pertenezcan a una región diferente de la configurada en tu Mac — una SIM francesa en una Mac configurada en en_US, por ejemplo:

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"],
      "env": { "MAC_MESSAGES_REGION": "FR" }
    }
  }
}

Para Claude Code:

claude mcp add --transport stdio --scope user \
  --env MAC_MESSAGES_REGION=FR \
  mac-messages -- uvx mac-messages-mcp

La región se resuelve una vez al inicio, así que reinicia el servidor después de cambiarla. Orden de resolución: MAC_MESSAGES_REGION, luego la preferencia AppleLocale de macOS, luego LC_ALL / LC_CTYPE / LANG, luego US. Los números ya escritos en E.164 (+33639980001) nunca se reinterpretan y no necesitan nada de esto.

Herramientas disponibles

Herramienta	Propósito	Efecto secundario
`tool_get_recent_messages`	Leer mensajes recientes, opcionalmente filtrados por contacto o ID de chat grupal	Solo lectura
`tool_fuzzy_search_messages`	Buscar cuerpos de mensajes por coincidencia aproximada de texto; por defecto 30 días, o usa `hours=0` para todo el historial	Solo lectura
`tool_find_contact`	Coincidir aproximadamente un nombre en Contactos y devolver números de teléfono	Solo lectura
`tool_get_chats`	Listar chats grupales con nombre y sus identificadores	Solo lectura
`tool_search_attachments`	Encontrar metadatos de archivos adjuntos por fecha, contacto, tipo MIME y límite	Solo lectura
`tool_get_attachment`	Obtener un archivo adjunto por ID, en línea cuando se admite o como ruta local	Solo lectura
`tool_check_imessage_availability`	Verificar la disponibilidad probable de iMessage para un número de teléfono o correo	Solo lectura
`tool_check_db_access`	Diagnosticar acceso a `~/Library/Messages/chat.db`	Solo lectura
`tool_check_contacts`	Devolver un recuento de contactos y una pequeña muestra	Solo lectura
`tool_check_addressbook`	Diagnosticar acceso a la base de datos de Contactos/Directorio	Solo lectura
`tool_send_message`	Enviar un mensaje directo o grupal a través de Messages.app	Envía un mensaje real

El servidor también expone dos recursos MCP:

messages://recent/{hours}
messages://contact/{contact}/{hours}

Trabajar con contactos, chats y archivos adjuntos

Destinatarios

Para mensajes directos, los números de teléfono E.164 son el formato más confiable:

+14155551234

Los números escritos en formato nacional también funcionan. Se expanden a E.164 usando la región para la que está configurada tu Mac, por lo que (415) 555-1234 se convierte en +14155551234 en una Mac de EE. UU. y 06 39 98 00 01 se convierte en +33639980001 en una francesa. Configura MAC_MESSAGES_REGION a un código ISO 3166-1 alpha-2 (MAC_MESSAGES_REGION=GB) cuando tus números pertenezcan a una región diferente de la de tu Mac. Los números ya en E.164 nunca se reinterpretan.

El servidor también acepta direcciones de correo, nombres de contacto y selecciones de contact:N devueltas después de una búsqueda de contacto ambigua.

Para una conversación grupal, llama a tool_get_chats, pasa su ID de chat a tool_send_message y configura group_chat=true. Usa el mismo ID como chat_id en tool_get_recent_messages para leer esa conversación.

Archivos adjuntos

El acceso a archivos adjuntos se divide deliberadamente en tres pasos:

Las lecturas y búsquedas de mensajes agregan marcadores compactos como [attachments: #42 image/jpeg (invitation.jpg)].
tool_search_attachments busca metadatos sin cargar el contenido de los archivos.
tool_get_attachment obtiene un archivo adjunto seleccionado.

Las imágenes de hasta 5 MB se devuelven en línea por defecto. Las imágenes HEIC se convierten a PNG. Las imágenes más grandes, PDF, video y audio se devuelven como rutas del sistema de archivos local para que el cliente MCP decida si abrirlos. Las pegatinas, cargas útiles de vista previa de enlaces y contenedores .pluginPayloadAttachment se filtran.

Privacidad y seguridad

Las conexiones SQLite de Mensajes y Contactos usan modo solo lectura y SQLite query_only.
El servidor no sube, replica, indexa ni mantiene su propio archivo de mensajes.
Los resultados se escriben en la conexión stdio MCP local iniciada por tu cliente.
La salida de herramientas y recursos derivada de Mensajes/Contactos se neutraliza estructuralmente (los saltos de línea incrustados y los controles ASCII no pueden formar líneas de transcripción adicionales; los caracteres invisibles, de formato y bidireccionales se muestran como escapes) y se devuelve dentro de un bloque <untrusted-mcp-output> explícito. Eso no es una garantía anti-inyección: el contenido de iMessage/SMS de terceros aún puede intentar inyección de indicaciones. El servidor hace que ese contenido sea no estructural y etiquetado; el cliente no debe tratarlo como autorización, confirmación o instrucciones de herramienta.
Los bytes de archivos adjuntos se devuelven solo después de una obtención explícita y tienen límite de tamaño para imágenes en línea. El nombre de archivo, MIME, ruta y otro texto de metadatos se neutraliza con el mismo límite; las cargas útiles de imagen se conservan.
El envío está aislado en tool_send_message, escapa las entradas de AppleScript y usa un tiempo de espera de ejecución limitado. Este servidor no realiza confirmación humana; el cliente MCP debe controlar los envíos.
El Acceso Total al Disco es más amplio que el acceso a Mensajes. Concédelo solo a clientes MCP en los que confíes y revisa el destino antes de aprobar un envío.

Consulta SECURITY.md para informar una vulnerabilidad de forma privada.

Solución de problemas

`uvx` o `spawn uvx ENOENT`

La app GUI no puede ver la ruta de Homebrew de tu shell. Ejecuta:

which uvx

Usa esa ruta completa como command de MCP y luego reinicia el cliente.

`Operation not permitted`, `unable to open database file` o sin mensajes

Otorga Acceso Total al Disco a la app que lanza el servidor, no solo a Messages.app. Sal y vuelve a abrir completamente el lanzador después, y luego llama a tool_check_db_access nuevamente.

Para Claude Code o Codex CLI, el lanzador normalmente es tu terminal. Para una integración de escritorio o IDE, normalmente es Claude Desktop, Cursor, VS Code o la propia app de escritorio de ChatGPT.

Los contactos están vacíos o la búsqueda de contactos falla

Permite que la app lanzadora acceda a Contactos si macOS lo solicita. Confirma el Acceso Total al Disco, reinicia la app y llama a tool_check_addressbook seguido de tool_check_contacts. Si los contactos aparecen listados pero sus números llevan el código de país incorrecto, el servidor está expandiendo tus números en formato nacional contra la región equivocada. Establece MAC_MESSAGES_REGION al código ISO 3166-1 alpha-2 correcto y reinicia el servidor.

La lectura funciona pero el envío falla

Abre Messages.app y envía un mensaje manualmente para confirmar que la cuenta y el destinatario funcionan.
Revisa Configuración del Sistema → Privacidad y Seguridad → Automatización y permite que la aplicación lanzadora controle Messages.
Prefiere un número E.164 como +14155551234 para un destinatario directo.
Usa tool_check_imessage_availability para inspeccionar la ruta probable.

Un adjunto aparece listado pero no se puede abrir

Messages puede conservar metadatos de la base de datos después de que macOS haya descargado el archivo. Abre la conversación en Messages.app y descarga el adjunto, luego reintenta tool_get_attachment.

El servidor parece colgarse cuando se ejecuta en Terminal

Eso es normal para un servidor MCP stdio: espera entrada de protocolo desde un cliente. Usa la vista de estado MCP de tu cliente, o lanza el MCP Inspector:

yarn dlx @modelcontextprotocol/inspector uvx mac-messages-mcp

Instalar como herramienta independiente

Los clientes MCP pueden lanzar el paquete directamente con uvx; una instalación permanente es opcional.

uv tool install mac-messages-mcp
mac-messages-mcp

Actualízalo o elimínalo con:

uv tool upgrade mac-messages-mcp
uv tool uninstall mac-messages-mcp

API de Python

El servidor MCP es la interfaz principal, pero el paquete también exporta sus funciones principales de lectura/envío:

from mac_messages_mcp import get_recent_messages, send_message

recent = get_recent_messages(hours=48)
print(recent)

result = send_message(
    recipient="+14155551234",
    message="Hello from Mac Messages MCP!",
)
print(result)

Estas llamadas usan los mismos permisos de macOS y pueden enviar mensajes reales.

Desarrollo

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

uv sync --frozen --extra dev
uv run pytest
uv run black --check .
uv run isort --check-only .
uv build

Las pruebas simulan AppleScript y usan accesorios de base de datos temporales; nunca deben leer datos reales de Messages o Contactos de un colaborador. Consulta CONTRIBUTING.md para la lista de verificación de contribuciones y VERSIONING.md para los lanzamientos.

Construir la extensión de Claude Desktop

El repositorio incluye un MCPB manifest.json y un script de compilación que puede empaquetar un binario uv específico de arquitectura:

yarn global add @anthropic-ai/mcpb
uv run python scripts/build_mcpb.py

Para una compilación Intel:

uv run python scripts/build_mcpb.py --arch x86_64

Instala el .mcpb generado desde Claude Desktop → Configuración → Extensiones → Configuración avanzada → Instalar extensión…. Una extensión empaquetada aún necesita acceso a la red en el primer lanzamiento para descargar Python y las dependencias del paquete.

Usa --no-bundle para empaquetar contra el uv del sistema, o ejecuta uv run python scripts/build_mcpb.py --help para cada opción.

Docker

El Dockerfile incluido es para validación de paquetes y catálogos. Un contenedor Linux no puede acceder a los permisos TCC de macOS ni automatizar Messages.app, por lo que Docker no es una forma compatible de leer o enviar mensajes en el Mac anfitrión.

Licencia

Contribuciones

Las incidencias y solicitudes de extracción enfocadas son bienvenidas. No incluyas contenidos reales de mensajes, contactos, números de teléfono, archivos de base de datos o adjuntos en informes de errores o accesorios.

Changelog · Contributing · Security · PyPI

Mac Messages MCP

Documentación

Mac Messages MCP

Qué puede hacer

Inicio rápido

1. Instalar uv

2. Otorgar permisos de macOS

3. Agregar el servidor a tu cliente MCP

Claude Desktop

Claude Code

Codex CLI, extensión IDE de Codex y app de escritorio de ChatGPT

Cursor

VS Code / GitHub Copilot

Otros clientes MCP stdio

4. Verificar la conexión

5. Opcional: configurar la región del número de teléfono

Herramientas disponibles

Trabajar con contactos, chats y archivos adjuntos

Destinatarios

Archivos adjuntos

Privacidad y seguridad

Solución de problemas

uvx o spawn uvx ENOENT

Operation not permitted, unable to open database file o sin mensajes

Los contactos están vacíos o la búsqueda de contactos falla

La lectura funciona pero el envío falla

Un adjunto aparece listado pero no se puede abrir

El servidor parece colgarse cuando se ejecuta en Terminal

Instalar como herramienta independiente

API de Python

Desarrollo

Construir la extensión de Claude Desktop

Docker

Licencia

Contribuciones

1. Instalar `uv`

`uvx` o `spawn uvx ENOENT`

`Operation not permitted`, `unable to open database file` o sin mensajes