Mac Messages Host

macOS의 Apple Messages(iMessage/SMS) 전체 기록을 AI 에이전트를 위해 읽기 전용으로 제공합니다. REST/OpenAPI와 streamable HTTP MCP를 통한 단일 배치(batched) 도구입니다.

• 단일 도구, 배치 요청: 하나의 messages(requests: str) 도구가 JSON 요청 배열을 받아 정렬된 JSON 응답 배열을 반환합니다. 즉, 한 번의 호출로 여러 독립 작업을 수행합니다. REST(POST /api/messages)와 MCP(/mcp/)에서 동일하게 제공됩니다.

• 구조적으로 읽기 전용: 데이터베이스는 SQLite mode=ro로 열리며 쓰기 경로가 없습니다. 보내기, 편집, 삭제는 불가능합니다.

• 최신 macOS 본문 디코딩: Ventura 이상에서 attributedBody typedstream blob에 저장된 메시지 텍스트와 message_summary_info plist의 편집 기록을 투명하게 디코딩합니다.

• 자동 생성 도구 프롬프트: AI 대상 프롬프트는 Pydantic 모델에서 생성됩니다(~615 gpt-4o 토큰, tiktoken으로 계산되고 테스트에 의해 강제됨), tool_prompt.md 스냅샷은 드리프트 테스트에 의해 동기화됩니다.

설치

macOS에서 Python 3.11+가 필요합니다.

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

macOS 권한(중요)

~/Library/Messages/chat.db는 macOS TCC로 보호됩니다. mmhost를 실행하는 프로세스에는 전체 디스크 접근 권한이 필요합니다.

시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한 → 터미널 앱(또는 서버를 실행하는 모든 것)을 활성화한 다음 다시 시작하세요.

mmhost info는 데이터베이스를 읽을 수 있는지 즉시 알려줍니다.

Related MCP server: jons-mcp-imessage

엔드포인트

인증

Authorization: Bearer <token>는 admin_token이 구성되었을 때 사용됩니다(영구 구성, MMHOST_ADMIN_TOKEN, 또는 --admin-token). 토큰이 구성되지 않으면 접근이 열려 있습니다. 서버가 기본적으로 127.0.0.1에 바인딩되므로 안전합니다.

요청 종류

• get_info — 데이터베이스 상태, 개수, 기록 날짜 범위

• list_chats — 최근 활동별 대화 목록(필터, 페이지네이션)

• get_chat — 채팅의 대화 내용(before로 이전 페이지네이션)

• get_recent — 모든 채팅의 최신 메시지(since로 폴링)

• search_messages — 본문에 대한 대·소문자 무시 부분 문자열 검색

정확한 AI 대상 문서는 tool_prompt.md를 참조하세요(모델에서 생성됨).

예시

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

MCP 클라이언트 구성

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

구성

플랫폼 구성 디렉토리(macOS에서는 ~/Library/Application Support/mac_messages_host/config.json)에 저장됩니다. MMHOST_CONFIG로 위치를 재정의할 수 있습니다. 서버 수준 설정만 있습니다. example.env 를 참조하세요.

개발

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

아키텍처는 oWoHo AI Tool Server 패턴(순수 코어 라이브러리 + 파생된 FastAPI/FastMCP/CLI 인터페이스)을 따르며, reddit_tool_server와 obsidian_ai_miniserver와 같습니다.

라이선스

MIT — LICENSE.md 를 참조하세요.