lane-mac-mcp

macOS용 읽기 전용 iMessage MCP 서버 + CLI입니다. 감사 가능한 단일 파일이며, 전송 기능이 없습니다.

Claude는(MCP를 통해) 또는 사용자는(CLI를 통해) 대화 목록을 보고, 채팅을 읽고, 메시지 기록을 검색할 수 있습니다. 그 외에는 아무것도 할 수 없습니다. 구조적으로 읽기 전용입니다. v1에는 전송 코드가 전혀 포함되어 있지 않습니다. 모든 데이터 접근은 Apple 자체의 /usr/bin/sqlite3을 -json -readonly 플래그와 함께 ~/Library/Messages/chat.db에 대해 실행하는 방식이며, 연락처 이름은 로컬 AddressBook 데이터베이스에 대한 읽기 전용 쿼리로 가져옵니다.

설계 제약

전체 서버는 server.ts(주석 포함 약 600줄)로, 종단 간 감사가 가능합니다. Node ≥ 22.18이 네이티브 타입 제거를 통해 TypeScript를 직접 실행하므로(빌드 단계나 컴파일 산출물 없음) 감사된 파일이 곧 실행 중인 파일입니다. 의존성은 정확히 두 가지이며, package-lock.json을 통해 고정되어 있습니다: @modelcontextprotocol/sdk와 zod. 네트워크 임포트도, 열린 포트도 없습니다. 오직 stdio JSON-RPC만 사용하며, Claude Desktop이 하위 프로세스로 실행합니다. CLI 실행은 일회성 프로세스입니다. 데몬은 없습니다. Claude Desktop은 앱과 함께 서버를 시작하고 종료합니다(코드를 다시 로드하려면 앱을 재시작하세요).

Related MCP server: imessage-rich-search

요구 사항

Messages가 설정된 macOS, Node.js ≥ 22.18, 그리고 서버를 실행하는 프로세스에 대한 Full Disk Access 권한이 필요합니다: CLI 사용 시 터미널(또는 터미널 앱), MCP 사용 시 Claude Desktop. System Settings → Privacy & Security → Full Disk Access에서 권한을 부여한 후 앱을 재시작하세요. node server.ts doctor가 이 모든 것을 확인하고 무엇이 빠졌는지 알려줍니다.

설정

git clone <this repo> && cd MacMCPServer
npm install          # installs the two pinned dependencies
node server.ts doctor

그런 다음 Claude Desktop의 claude_desktop_config.json에 서버를 추가합니다 (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "lane-mac": {
      "command": "node",
      "args": ["/Users/you/Desktop/MacMCPServer/server.ts"]
    }
  }
}

Claude Desktop을 재시작하세요. 다음 세 가지 도구가 나타납니다: list_chats, read_chat, search_messages.

CLI 사용법

node server.ts chats                                   # recent chats, names resolved
node server.ts chats --search "mom" --limit 5
node server.ts chats --awaiting-reply-only             # threads where the last word wasn't yours
node server.ts read "Martha" --limit 100               # fuzzy name; ambiguous → candidates
node server.ts read 42 --start-date 2024-01-01 --end-date 2024-06-30 --include-reactions
node server.ts search "dinner" --from "martha"         # last 30 days by default
node server.ts search "dinner" --start-date 2015-01-01 --deep   # older history + rich-text decode
node server.ts doctor

출력은 JSON입니다. search는 SQL LIKE를 사용해 message.text를 검색합니다. --deep은 텍스트가 attributedBody 블롭에만 있는 메시지도 추가로 디코딩합니다(범위 제한 스캔, 더 느림). Tapback 반응은 --include-reactions가 없는 한 모든 곳에서 제외됩니다.

Apple 특이사항 처리

타임스탬프는 2001-01-01 이후의 나노초 단위입니다(매우 오래된 행은 초 단위). 둘 다 변환됩니다. 메시지 텍스트는 message.text가 아니라 attributedBody typedstream 블롭에 있는 경우가 많습니다. JS에서 알려진 NSString 휴리스틱으로 디코딩됩니다. 연락처 이름은 모든 AddressBook 소스에서 정규화된 마지막 10자리 전화번호 또는 소문자 이메일로 매칭되며, 연락처를 읽을 수 없는 경우 원시 번호로 자연스럽게 폴백됩니다.

개인정보 보호 및 안전 원칙

서버는 오직 읽기만 할 수 있습니다. sqlite3의 -readonly 플래그로 데이터베이스를 열며, 어떤 데이터베이스에 쓰거나 메시지를 보내는 코드 경로가 없고, 네트워크 연결을 만들지 않으며, 포트를 수신하지 않습니다. 사용자 입력은 SQL 문자열 리터럴로 이스케이프되고('' 이중화) 숫자는 검증됩니다. doctor는 행 수만 출력하며 메시지 내용은 절대 출력하지 않습니다. 환경 변수 재정의(CHAT_DB_PATH, SQLITE_BIN, ADDRESSBOOK_DIR)가 있어 테스트가 실제 데이터를 건드리지 않습니다.

테스트

npm test

블랙박스 테스트는 합성 chat.db와 AddressBook 픽스처를 생성하고(attributedBody에만 있는 메시지, Tapback, 답장하지 않은 수신 스레드 포함) 실제 CLI와 실제 MCP stdio 인터페이스를 하위 프로세스로 구동합니다. 개발 중에는 실제 데이터를 절대 건드리지 않습니다.

로드맵(나중에, v1 아님)

연락처 보강 다듬기 → osascript를 통한 메모 읽기 → SEND_ENABLED 환경 변수와 호출별 승인을 통해 게이트된 전송.