imessage-mcp

Mac의 iMessage 데이터를 Claude Desktop / Claude Code에 노출하는 로컬 MCP 서버입니다. 두 가지 기능:

1. 전송: AppleScript → Messages.app을 통해 전송

2. 읽기: ~/Library/Messages/chat.db에 대한 직접적인 읽기 전용 SQLite 액세스를 통해 읽기

모든 데이터는 로컬에 유지됩니다. API 키나 네트워크 호출이 없습니다.

설치

# 1. Clone / copy into ~/mcp-servers/imessage-mcp
cd ~/mcp-servers/imessage-mcp

# 2. Create a Python 3.11+ venv and install deps
python3.12 -m venv .venv
.venv/bin/pip install -e .

Related MCP server: imessage-mcp

권한 (필수)

전체 디스크 접근 권한 — chat.db를 읽기 위해 필요

시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한 → 다음 항목을 켬(ON)으로 설정:

• 터미널 앱 (예: Terminal, iTerm2, Ghostty), 그리고

• Claude.app (Claude Desktop을 사용하는 경우)

자동화 — Messages.app을 제어하기 위해 필요

시스템 설정 → 개인정보 보호 및 보안 → 자동화 → 터미널 / Claude.app을 확장하고 **메시지(Messages)**를 켬(ON)으로 설정합니다.

Messages.app이 실행 중이어야 하며 iMessage에 로그인되어 있어야 합니다.

권한 설정 단계가 누락된 경우, 서버는 열어야 할 정확한 설정 경로와 함께 오류를 반환합니다.

Claude Desktop 설정

~/Library/Application Support/Claude/claude_desktop_config.json에 병합하세요:

{
  "mcpServers": {
    "imessage": {
      "command": "/Users/YOUR_USERNAME/mcp-servers/imessage-mcp/.venv/bin/python",
      "args": ["-m", "imessage_mcp.server"]
    }
  }
}

(venv의 파이썬 절대 경로를 사용하는 것이 가장 안전합니다. PATH 모호성을 방지합니다. YOUR_USERNAME을 본인의 사용자 이름으로 바꾸세요.)

도구

날짜는 입출력 시 ISO8601 형식을 사용합니다. 내부적으로 Apple은 message.date를 2001년 1월 1일 UTC 이후의 나노초 단위로 저장하며, 서버는 이를 양방향으로 변환합니다.

안전 불변성

• chat.db는 sqlite3.connect("file:...chat.db?mode=ro", uri=True)로 열립니다. 쓰기를 시도하면 sqlite3.OperationalError: attempt to write a readonly database 오류가 발생합니다.

• send_imessage는 수신자/본문/서비스를 별도의 osascript argv 항목으로 전달하므로 셸 보간이나 인젝션이 발생하지 않습니다.

• 첨부 파일은 메타데이터(파일명, mime_type, 총 바이트 수)만 반환합니다. 블롭(Blob) 데이터는 절대 읽지 않습니다.

제한 사항

• 예약/지연 전송은 지원되지 않습니다.

• 리치 메시지/답글 스레드 메시지는 텍스트가 attributedBody(NSKeyedArchive)에 저장될 수 있습니다. 포함된 NSString을 추출하기 위해 최선을 다하지만, 더 복잡한 페이로드(이미지, 탭, Apple Pay 등)가 포함된 메시지는 body가 비어 있거나 올바른 메타데이터만 표시될 수 있습니다.

• 전송 확인: send_imessage는 osascript의 종료 코드를 통해 성공 여부를 보고합니다. 메시지가 실제로 전송되었는지 확인하려면 몇 초 후에 search_imessages 또는 get_chat_messages를 호출하세요.

• 이 도구는 macOS 전용이며 샌드박스 처리된 App Store 앱에서는 작동하지 않습니다.

로컬 개발

.venv/bin/pytest -q