멀티모달 iMessage MCP

Claude를 위한 가장 완벽한 iMessage MCP 서버입니다. 전체 대화 읽기, 메시지 검색, 이미지 첨부 파일 보기, 메시지 보내기, 연락처 조회, 메시지에 반응하기 — 모두 Claude Desktop 또는 Claude Code에서 가능합니다.

존재 이유

다른 모든 iMessage MCP 도구는 Apple의 chat.db에서 text 열을 조회합니다. 문제는? 최신 macOS(14+)에서는 93%의 메시지가 text 대신 attributedBody에 저장됩니다. 해당 도구들은 조용히 빈 대화나 불완전한 대화를 반환합니다.

이 서버는 Apple의 NSAttributedString 바이너리 형식을 리버스 엔지니어링하여 실제 메시지 내용을 추출하므로 완전한 메시지 기록에 접근할 수 있습니다.

Related MCP server: jons-mcp-imessage

기능

멀티모달: Claude가 사진을 볼 수 있습니다

get_attachment를 사용하면 이미지가 base64 콘텐츠 블록으로 반환되어 Claude가 실제로 볼 수 있습니다. HEIC 사진(iPhone 기본값)은 자동으로 JPEG로 변환됩니다. 즉, Claude는 다음을 할 수 있습니다:

• 누군가 보낸 사진에 무엇이 있는지 설명

• 이미지에서 텍스트/스크린샷 읽기

• 대화에서 시각적 콘텐츠 분석

요구 사항

• macOS (로컬 iMessage 데이터베이스를 읽습니다)

• Node.js >= 18 및 < 26. Node 24 LTS를 권장합니다. 고정된 네이티브 SQLite 종속성이 Node 26과 호환되지 않기 때문입니다.

• 터미널 앱에 전체 디스크 접근 권한이 부여되어야 합니다 (시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근). 이는 iMessage 데이터베이스와 연락처 이름 확인에 사용되는 AddressBook 데이터베이스를 모두 포함합니다 — Contacts 앱이 실행 중일 필요는 없습니다.

설치

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

구성

Claude Desktop

다음을 ~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

중요: Node.js 바이너리의 전체 경로(예: /opt/homebrew/bin/node)를 사용하고, 단순히 node를 사용하지 마세요. macOS 데스크톱 앱은 셸의 PATH를 상속하지 않으며, node 명령어만 사용하면 종종 네이티브 모듈 충돌을 일으키는 이전 시스템 Node로 확인됩니다.

Claude Code

다음을 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

Claude Code에서는 node가 일반적으로 셸 환경을 상속하므로 올바르게 확인됩니다.

사용 예

"최근 메시지 보여줘" -- 최신 대화 읽기

"엄마가 오늘 뭐라고 문자 보냈어?" -- "엄마"를 AddressBook을 통해 전화번호로 확인하고 대화를 가져옴

"내 메시지에서 'flight confirmation' 검색" -- 모든 메시지 전체 텍스트 검색

"지난 7일 동안 답장했고 후속 조치가 필요한 아웃리치 대상 찾기" -- 위험 레이블이 있는 구조화된 아웃리치 후보 반환

"이 10개의 후속 문자 배치 미리보기" -- 전송 전에 정확한 수신자, 메시지, 경고 및 승인 토큰 반환

"최근 전송 실패 보기" -- Messages가 실패 또는 보류 중으로 표시한 발신 메시지 보고, 이후 SMS/RCS 전송이 스레드를 복구했는지 여부 포함

"메시지 538516의 사진 보여줘" -- Claude가 보고 설명할 실제 이미지 반환

"+1234567890에 'Running 10 min late' 보내기" -- iMessage 전송 (확인 필요)

릴리스 플래그

릴리스 플래그는 MCP 서버 환경을 통해 선택적으로 활성화됩니다:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

변형 도구

delete_messages는 정확한 메시지 ROWID를 허용합니다:

{ "message_ids": ["538516", "538517"] }

확인이 필요하지 않습니다. 삭제된 ID, 누락된 ID, 백업 위치, 확인 중 발견된 남은 행을 보고합니다.

delete_threads는 두 단계의 정확한 배치 흐름입니다:

{ "chat_ids": [101, 102] }

미리보기는 해당 순서 목록과 미리보기에 표시된 스레드 메타데이터에 대한 하나의 approval_token을 반환합니다. 삭제하려면 동일한 순서의 chat_ids, confirm: true, 해당 토큰을 보내세요:

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

순서, 목록 또는 토큰을 변경하면 요청이 실패합니다.

edit_message 및 undo_send_message는 실험적입니다. Messages가 해당 작업에 대한 일급 AppleScript 명령을 노출하지 않기 때문입니다. 대화를 열고, 텍스트 조각으로 보이는 발신 말풍선을 찾고, 컨텍스트 메뉴를 사용한 다음 결과를 확인합니다. 이는 실제 Messages 동작에 영향을 미치기 위한 것이며, 가짜 로컬 전용 DB 편집이 아닙니다.

선택적 조정:

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

이는 MCP가 새 발신 행에 대해 로컬 Messages 데이터베이스를 확인하기 전에 대기하는 시간을 제어합니다.

작동 방식

attributedBody 수정

Apple의 iMessage 데이터베이스(~/Library/Messages/chat.db)에는 메시지 내용을 위한 두 개의 열이 있습니다:

• text -- 레거시 일반 텍스트 열 (이전 macOS 버전에서 사용)

• attributedBody -- 직렬화된 NSAttributedString blob (macOS 14+에서 사용)

최신 macOS에서 Apple은 리치 텍스트, 멘션, 서식을 지원하기 위해 메시지 저장을 점차 attributedBody로 마이그레이션했습니다. text 열은 점점 더 자주 NULL인 레거시 폴백에 불과합니다.

이 서버는 NULL 텍스트가 있는 메시지를 감지하고 바이너리 NSTypedStream 형식을 파싱하여 attributedBody에서 내용을 추출합니다:

1. 바이너리 blob에서 NSString 마커 찾기

2. 유형 헤더 바이트(01 94 84 01 2b)를 지나 읽기

3. 길이 접두사 디코딩 (짧은 메시지는 단일 바이트, 긴 메시지는 다중 바이트)

4. UTF-8 텍스트 페이로드 추출

첨부 파일 처리

iMessage 첨부 파일은 ~/Library/Messages/Attachments/에 저장되며 경로는 attachment 테이블에서 추적됩니다. get_attachment 도구:

1. 주어진 메시지 ID에 대한 첨부 파일 메타데이터 조회

2. ~/Library/Messages/... 경로를 절대 경로로 확인

3. JPEG/PNG/GIF/WebP의 경우: 파일을 읽고 base64 이미지 콘텐츠 반환

4. HEIC(iPhone 기본값)의 경우: 반환 전에 macOS sips를 사용하여 JPEG로 변환

5. 다른 파일의 경우: 메타데이터와 파일 경로 반환

문제 해결

"iMessage 데이터베이스를 열지 못했습니다" 터미널 앱에 전체 디스크 접근 권한을 부여하세요: 시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근.

연락처 조회 결과 없음 연락처 확인은 macOS AddressBook SQLite 데이터베이스를 직접 읽습니다(Contacts 앱 필요 없음). 전체 디스크 접근 권한이 부여되었는지 확인하세요. 연락처를 방금 추가한 경우 MCP 서버를 다시 시작하여 캐시를 새로 고치세요.

네이티브 모듈 충돌 / "NODE_MODULE_VERSION 불일치" 네이티브 종속성 재빌드: npm rebuild. Node.js 버전이 변경될 때 발생합니다. 또한 Claude Desktop 구성이 node의 전체 경로를 사용하는지 확인하세요(위 구성 참조).

대화에서 메시지 누락 이것이 바로 이 서버가 수정하는 버그입니다. attributedBody 추출을 포함한 최신 버전을 실행 중인지 확인하세요.

라이선스

MIT

빠른 시작 TL;DR

npm install
node index.js

그런 다음 서버를 MCP 클라이언트 설정에 추가하고 터미널 앱에 전체 디스크 접근 권한을 부여하세요.

작동 방식 (TL;DR)

• macOS iMessage SQLite 데이터베이스 읽기

• 최신 attributedBody 페이로드를 디코딩하여 완전한 메시지 텍스트를 추출

• MCP를 통해 대화/검색/첨부 파일 도구를 노출

• 명시적 확인과 함께 메시지 보내기/반응 작업을 위해 AppleScript 사용

LLM 빠른 복사

GitHub에서 이 코드 블록의 복사 버튼을 사용하세요.

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools