Skip to main content
Glama

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을 본인의 사용자 이름으로 바꾸세요.)

도구

도구

목적

send_imessage(recipient, body, service?)

Messages.app을 통해 전송합니다. recipient는 전화번호, Apple ID 이메일 또는 기존 친구 이름입니다.

list_recent_chats(limit=20)

마지막 메시지 미리보기와 읽지 않은 메시지 수를 포함하여 최신순으로 채팅을 나열합니다.

get_chat_messages(chat_id?, handle?, limit=50, since?)

채팅 메시지를 가져옵니다. chat_id 또는 handle을 제공하세요.

search_imessages(query, since?, until?, from_contact?, limit=25)

메시지 본문에서 대소문자를 구분하지 않고 검색(LIKE)합니다.

get_my_info()

내 핸들(Self-handles) 및 DB 메타데이터를 가져옵니다.

날짜는 입출력 시 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

Available Tools

6 tools
get_chat_messagesA

Return messages for a chat. Provide chat_id or handle (phone/email).

since is an ISO8601 datetime. Attachments are metadata only.

Inputs: chat_id, handle, limit, since. Returns: result

get_my_infoA

Return self-handles and chat.db metadata for sanity checks.

Inputs: no named parameters. Returns: object

list_recent_chatsB

List recent chats, newest-first, with previews and unread counts.

Inputs: limit. Returns: result

resolve_contactA

Resolve an iMessage handle to a name, or a name to handles.

Provide either handle (phone like +15551234567 or email) or name. Checks a local JSON cache first, then falls back to the macOS AddressBook SQLite. New hits are written back to the cache for future sessions.

Inputs: name, handle. Returns: object

search_imessagesA

Case-insensitive LIKE search over message bodies. Dates are ISO8601.

Inputs: query (required), since, until, from_contact, +1 more. Returns: result

send_imessageA

Send an iMessage/SMS via Messages.app.

Args: recipient: phone (+15551234567), Apple ID email, or an existing buddy name. body: message text. service: "iMessage" (default) or "SMS".

Inputs: recipient (required), body (required), service. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: retrieving messages by chat or search, listing chats, resolving contacts, sending messages, and getting self info. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_, list_, resolve_, search_, send_), making the API predictable and easy to navigate.

    Tool Count5/5

    With 6 tools covering core iMessage operations (read, send, search, list, resolve), the set is well-scoped and each tool earns its place without unnecessary bloat.

    Completeness4/5

    Covers essential CRUD-like operations (read via chat or search, send, list) plus contact resolution and self-info. Missing message deletion or editing, but those are uncommon for MCP servers, so no significant gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables full-text search of macOS iMessages including link preview metadata. Works as an MCP server for Claude Desktop to search your messages locally.
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that exposes your iMessage data to Claude Code and Claude Desktop, with automatic contact name resolution.
      3
      -
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that lets Claude Desktop interact with Apple Mail on macOS via AppleScript. It enables listing mailboxes, searching emails, and reading email content without making network calls.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Local MCP server for reading macOS Messages history and sending iMessages, with security features like opt-in send tools and recipient allowlists.
      4
      MIT