iMessage MCP

여러분의 macOS Messages 기록을 읽고 새 iMessage를 보내는 로컬 MCP 서버입니다. 모든 것이 로컬에서 실행됩니다 — 아무것도 여러분의 컴퓨터 밖으로 나가지 않습니다.

도구

읽기 도구는 호출당 200행으로 제한되며 탭백은 포함하지 않습니다. 두 전송 도구는 IMESSAGE_MCP_ALLOW_SEND=1이 설정되지 않는 한 전혀 등록되지 않으므로, 읽기 전용으로 구성된 호스트는 우연히도 보낼 수 없습니다.

Related MCP server: imessage-mcp

보안 모델

여러분의 메시지를 읽는 것과 여러분으로서 보내는 것은 매우 다른 권한이며, 둘을 하나의 에이전트 세션에 두는 것이 위험한 부분입니다. 여러분에게 문자를 보낼 수 있는 사람은 누구나 get_recent_messages에 텍스트를 넣을 수 있으므로, 메시지 본문은 여러분으로서 메일을 보내는 도구 옆에 있는 공격자가 제어하는 입력입니다.

이 서버가 이에 대해 하는 일:

• 전송 도구는 기본적으로 꺼져 있으며 호스트별로 켜야 합니다.

• IMESSAGE_MCP_ALLOWED_RECIPIENTS는 메시지를 보낼 수 있는 대상을 제한합니다.

• 모든 전송 시도와 결과는 AppleScript 호출 전후에 로컬 감사 로그에 추가되므로, 기록 없이 전송이 일어날 수 없습니다.

• 발신 메시지는 길이 제한이 있으며 비어 있을 수 없습니다.

• 서버는 MCP instructions와 도구별 주석(readOnlyHint, destructiveHint)을 제공하여 호스트가 위험한 도구에 대해 확인 프롬프트를 표시할 수 있게 합니다.

하지 못하는 일: 악성 메시지를 읽은 모델이 그에 따라 행동하기로 결정하는 것을 막을 수 없습니다. 전송을 활성화한다면 전송 도구에 승인 프롬프트를 유지하세요.

구성

모두 선택 사항입니다. 셸 프로필이 아닌 MCP 호스트의 구성 파일에 설정하세요.

설정

git clone https://github.com/tarun101/imessage-mcp.git
cd imessage-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Python 3.10 이상. 아래 모든 내용은 $REPO가 클론의 절대 경로라고 가정합니다.

mcp 의존성은 <2로 고정되어 있습니다. 2.x SDK는 이 서버가 import하는 mcp.server.fastmcp를 제거했으므로, 고정하지 않은 설치에서는 2.x를 받아 시작 시 실패합니다.

macOS 권한 (둘 다 필요)

1. Full Disk Access — 없으면 ~/Library/Messages/chat.db 읽기가 차단됩니다. 서버를 실행하는 프로세스(Terminal, iTerm, 또는 MCP 호스트 앱)를 System Settings → Privacy & Security → Full Disk Access에 추가한 후 완전히 종료하고 다시 여세요.

2. Automation → Messages — 첫 번째 send_message/send_to_chat 호출은 Messages.app 제어를 위한 일회성 권한 프롬프트를 발생시킵니다. 허용하세요.

빠른 테스트

source .venv/bin/activate
python -c "import server; print(server.list_chats(5))"

테스트

pip install -e '.[dev]'
pytest

테스트 스위트는 Apple의 스키마로 합성 chat.db를 만들기 때문에 어디서든 실행됩니다 — Mac도, 실제 메시지 기록에 대한 접근도 필요 없습니다.

MCP 호스트에 등록

Codex

codex mcp add imessage --env IMESSAGE_MCP_ALLOW_SEND=1 -- \
  "$REPO/.venv/bin/python" "$REPO/server.py"

또는 ~/.codex/config.toml에서, 도구별 승인을 요구할 수도 있습니다:

[mcp_servers.imessage]
command = "/absolute/path/to/imessage-mcp/.venv/bin/python"
args = ["/absolute/path/to/imessage-mcp/server.py"]
default_tools_approval_mode = "auto"

[mcp_servers.imessage.env]
IMESSAGE_MCP_ALLOW_SEND = "1"

[mcp_servers.imessage.tools.send_message]
approval_mode = "prompt"

[mcp_servers.imessage.tools.send_to_chat]
approval_mode = "prompt"

Codex TUI에서 /mcp로 확인하세요.

Claude Code (CLI)

claude mcp add imessage -- "$REPO/.venv/bin/python" "$REPO/server.py"

Claude Desktop / 일반 MCP 구성

{
  "mcpServers": {
    "imessage": {
      "command": "/absolute/path/to/imessage-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/imessage-mcp/server.py"]
    }
  }
}

venv의 Python(mcp가 설치된)이 사용되도록 절대 경로를 사용하세요.

참고 사항 및 제한 사항

• 읽기 전용 DB 접근. chat.db는 mode=ro로 열립니다. 서버는 여러분의 메시지 저장소에 절대 쓰지 않습니다. 전송은 오직 Messages.app을 통해서만 이루어집니다.

• WAL 폴백. chat.db는 WAL 데이터베이스이며, 읽기 전용 핸들은 필요한 -shm 파일을 만들 수 없습니다. 직접 열기가 실패하면 — Messages.app이 실행 중이지 않을 때 발생 — 서버는 대신 임시 스냅샷 복사본을 투명하게 읽으며, 소스가 변경될 때마다 새로 고쳐집니다.

• attributedBody. 최신 메시지는 본문을 text 열 대신 이진 attributedBody blob에 저장합니다. 리더는 이를 휴리스틱하게 디코딩합니다 — 일반 텍스트 메시지는 처리하지만 리치 콘텐츠는 놓칠 수 있습니다. 이 때문에 search_messages는 일반 text 열만 매칭합니다.

• 타임스탬프는 ISO-8601 UTC로 반환됩니다.

• 전송은 검증되며, 가정되지 않습니다. AppleScript는 전달 전에 반환되므로, 전송 후 서버는 chat.db에서 발신 행을 폴링합니다. sent_unverified 결과는 Messages.app이 수락했지만 아직 도착하지 않았음을 의미합니다 — 보통 실패라기보다 지연입니다.

• 전송은 실제입니다. 이 도구들은 회수할 수 없는 실제 메시지를 보냅니다.