Mac Messages Host

Todo el historial de Apple Messages (iMessage/SMS) de tu Mac, en solo lectura, para agentes de IA — una herramienta por lotes sobre REST/OpenAPI y streamable HTTP MCP.

• Una sola herramienta, solicitudes por lotes: una única herramienta messages(requests: str) toma un array JSON de solicitudes y devuelve un array JSON alineado de respuestas — una sola llamada hace muchas operaciones independientes. Se sirve igual por REST (POST /api/messages) y por MCP (/mcp/).

• Solo lectura por construcción: la base de datos se abre con SQLite mode=ro; no hay vía de escritura. Nada se puede enviar, editar ni eliminar.

• Decodificación moderna del cuerpo del mensaje en macOS: el texto de los mensajes almacenado en blobs de tipo typedstream de attributedBody (Ventura+) y el historial de ediciones en plists de message_summary_info se decodifican de forma transparente.

• Prompt de herramienta autogenerado: el prompt orientado a la IA se genera a partir de los modelos Pydantic (~615 tokens de gpt-4o, contados por tiktoken y verificados por una prueba); una instantánea de tool_prompt.md se mantiene sincronizada mediante una prueba de desviación.

Instalación

Requiere Python 3.11+ en macOS.

pip install .            # or: pip install -e . for development
mmhost info              # permission check + database status
mmhost start             # serve API + MCP on http://127.0.0.1:8761

Permisos de macOS (importante)

~/Library/Messages/chat.db está protegido por el TCC de macOS. El proceso que ejecuta mmhost necesita Acceso completo al disco:

Ajustes del Sistema → Privacidad y Seguridad → Acceso completo al disco → habilita tu aplicación de terminal (o cualquier otra que lance el servidor) y reiníciala.

mmhost info te indica de inmediato si la base de datos es legible.

Related MCP server: jons-mcp-imessage

Endpoints

Autenticación

Authorization: Bearer <token> cuando admin_token esté configurado (configuración persistida, MMHOST_ADMIN_TOKEN o --admin-token). Sin token configurado, el acceso es abierto: seguro porque el servidor se vincula a 127.0.0.1 por defecto.

Tipos de solicitudes

• get_info — estado de la base de datos, recuentos, rango de fechas del historial

• list_chats — conversaciones por actividad reciente (filtrar, paginar)

• get_chat — transcripción de un chat (puedes paginar los anteriores con before)

• get_recent — mensajes más recientes de todos los chats (consulta mediante since)

• search_messages — búsqueda de subcadenas sin distinguir mayúsculas ni minúsculas en los cuerpos

Consulta tool_prompt.md para la documentación exacta orientada a la IA (generada a partir de los modelos).

Ejemplo

curl -s http://127.0.0.1:8761/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"requests": "[{\"kind\":\"list_chats\",\"limit\":3}]"}'

Configuración del cliente MCP

{
  "mcpServers": {
    "mac-messages": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8761/mcp/"
    }
  }
}

Configuración

Se guarda en el directorio de configuración de la plataforma (~/Library/Application Support/mac_messages_host/config.json en macOS); puedes cambiar la ubicación con MMHOST_CONFIG. Solo ajustes de nivel de servidor: consulta example.env.

Desarrollo

pip install -e '.[dev]'
pytest
# after changing request models:
python -m tests.regenerate_tool_prompt

La arquitectura sigue el patrón de oWoHo AI Tool Server (biblioteca principal pura + interfaces FastAPI/FastMCP/CLI derivadas), como reddit_tool_server y obsidian_ai_miniserver.

Licencia

MIT — consulta LICENSE.md.