<img src="https://raw.githubusercontent.com/anipotts/imessage-mcp/HEAD/assets/icon.svg" width="72" height="72" alt="">
imessage-mcp
npm MCP Registry CI License: MIT
Claude, Codex, Cursor, VS Code 및 기타 모든 MCP 클라이언트에서 메시지 기록을 검색하고 읽으세요.
Claude Code catching up on a real conversation about a hackathon through imessage-mcp
읽기 전용입니다. Mac에서 실행됩니다. 계정, 클라우드 서비스, 컴파일할 것이 없습니다.
- iMessage, SMS, MMS, RCS 전반에 걸쳐 단어, 정확한 텍스트 또는 구문으로 메시지 검색
- 편집된 내용, 전송되지 않은 메시지, 반응(reactions), 답장(replies), 읽음 확인란이 포함된 전체 대화 기록을 읽습니다.
- 위치 데이터가 제거된 사진을 보여줍니다.
- 변경 피드(change feed)를 통해 새 메시지를 추적하고, 메시지 개수 및 응답 시간 질문에 답변합니다.
설치 (Install)
요구 사항: macOS 14 이상. npx 설치를 위해 Node.js 24.16 이상. (Claude Desktop은 자체 버전을 제공함). 암호화된 캐시 지원을 위해서는 Node 24 LTS를 사용하세요. SQLite 체크포인트 API가 없는 런타임(Node 25 포함)에서는 메모리에서 검색하고 재시작 후 다시 구축합니다. doctor 명령어로 확인할 수 있습니다.
표준 설정은 mcpServers JSON을 읽는 모든 클라이언트용입니다:
{
"mcpServers": {
"imessage": {
...
이후 해당 앱에 전체 디스크 접근(Full Disk Access) 권한을 부여해야 합니다: 시스템 설정 > 개인 정보 보호 및 보안 > 전체 디스크 접근에서 앱(Claude, 터미널, Cursor, VS Code 등)을 켜고 완전히 종료했다가 다시 시작하세요. 어떤 앱인지 확실하지 않다면 해당 앱의 터미널에서 npx -y imessage-mcp@latest doctor를 실행하면 알려줍니다. 접근 권한이 부여될 때까지 모든 도구는 이와 동일한 단계를 거쳐 답변합니다.
<details>
<summary>Amp</summary>
amp mcp add imessage -- npx -y imessage-mcp@latest
</details>
<details>
<summary>Claude Code</summary>
claude mcp add --scope user imessage -- npx -y imessage-mcp@latest
</details>
또는 플러그인을 설치합니다: /plugin marketplace add anipotts/imessage-mcp, 그리고 /plugin install imessage-mcp@anipotts를 실행합니다.
</details>
<details>
<summary>Claude Desktop</summary>
imessage-mcp.mcpb를 다운로드하여 더블클릭하거나, 설정(Settings) > 확장 프로그램(Extensions)에 목록이 있다면 iMessage History를 설치합니다. 직접 설치한 번들을 업데이트하려면 최신 버전을 다운로드하여 다시 더블클릭하십시오.
그런 다음 Claude에서 전체 디스크 접근(Full Disk Access)을 켜고, Claude를 종료했다가 다시 시작합니다.
</details>
<details>
<summary>Cline</summary>
표준 설정을 cline_mcp_settings.json(문서)에 추가합니다.
</details>
<details>
<summary>Codex</summary>
codex mcp add imessage -- npx -y imessage-mcp@latest
또는 ~/.codex/config.toml에 다음을 추가합니다:
[mcp_servers.imessage]
command = "npx"
args = ["-y", "imessage-mcp@latest"]
</details>
<details>
<summary>Copilot CLI</summary>
/mcp add를 실행하거나, `
<details>
<summary>opencode</summary>
~/.config/opencode/opencode.json에 추가:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
...
</details>
<details>
<summary>VS Code</summary>
<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="VS Code에서 설치"> <img alt="VS Code Insiders에서 설치" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">
```bash
code --add-mcp '{"name":"imessage","command":"npx","args":["-y","imessage-mcp@latest"]}'
</details>
<details>
<summary>Warp, Windsurf, Zed 및 기타 클라이언트</summary>
클라이언트의 MCP 설정에 표준 구성을 추가하세요. Zed는 `
| prompt | what it does |
|---|
catch_up | Who is waiting on a reply from you, and what they need |
| ... | |
Clients가 리소스를 첨부할 수 있는 경우 imessage://conversations 및 imessage://conversations/{chat_id}를 사용할 수 있습니다. | |
| tool | what it does |
|---|
search_messages | 부분 문자열, 정확한 텍스트, 토큰 또는 구문으로 검색합니다. 기본적으로 메시지 텍스트이며, 대화 이름 및 첨부 파일 이름은 선택 사항입니다. 서비스, 전송/수신 여부, 날짜별로 필터링할 수 있습니다. |
| ... | |
모든 도구는 읽기 전용(read-only)이며 readOnlyHint가 표시됩니다. 결과는 도구 간에 전달할 수 있는 일반 ID(message_id, chat_id, attachment_id)를 사용합니다. | |
Apple은 동일한 메시지를 여러 대화에서 기록할 수 있습니다. 검색(Search)은 모든 표준화된 chat_ids와 해당 conversations 레이블을 가진 이 메시지를 한 번 반환합니다. 단일 멤버십(membership) 또한 chat_id와 conversation을 포함합니다. 공유된 결과를 위해서는 chat_ids에서 관련 ID를 get_conversation에 전달하십시오. 오직 Apple의 명시적인 조회 증거만이 채팅 별칭(chat aliases)을 결합할 수 있습니다. 공유 메시지는 관련 없는 대화를 결합하지 않습니다.
전역 및 연락처 메시지 카운트는 요청된 범위 내에서 공유 기록을 중복 제거합니다. 대화 타임라인과 순서 지표는 각 기록된 멤버십을 유지하므로, 대화별 카운트를 추가하면 전역 카운트를 초과할 수 있습니다. 동기화(Sync)는 변경 사항에 대한 chat_ids를 포함하고 previous_chat_ids와 함께 message_membership_changed를 방출합니다. 이의 changed_at은 Apple이 이러한 결합에 타임스탬프를 지정하지 않기 때문에 null입니다. 기록된 멤버십은 관찰될 때 변경 사항을 설명하며, 사용 가능한 텍스트, 발신자 및 수신 필드는 현재 소스 상태를 설명합니다. 인덱스 형식을 업그레이드하는 것은 캐시를 한 번 재구축하고 이전 동기화 커서(sync cursors)를 무효화합니다. DATABASE_CHANGED가 반환되면 새로운 동기화를 시작하십시오.
설정 (Configuration)
예를 들어, args에 옵션을 추가합니다: `[
| option | description |
|---|
--privacy <mode> | 호출자가 볼 수 있는 가장 높은 수준의 정보. full(기본값), redacted(이름 및 마스킹된 핸들, 캘린더 날짜만 표시하며 메시지 텍스트나 파일명은 제외), 또는 aggregate(카운트만). 호출은 더 엄격한 모드를 요청할 수 있지만, 더 느슨한 모드는 절대 요청할 수 없습니다. env IMESSAGE_PRIVACY |
| ... | |
개인 정보 보호 및 보안
- 읽기 전용(Read-only). 서버는 Messages 데이터베이스를 읽기 전용으로 열고, 메시지를 보내거나, 편집하거나, 반응을 추가하거나, 읽음 표시를 하는 도구가 없습니다.
- 로컬(Local). 계정, 원격 측정(telemetry), 또는 분석 기능이 없습니다. 유일한 네트워크 요청은 npm 레지스트리로의 선택적 버전 확인입니다.
- 클라이언트가 요청하는 것을 클라이언트가 봄. 결과는 사용자가 사용하는 MCP 클라이언트와 해당 모델 제공업체로 전송되며, 이는 그들의 정책을 따릅니다.
--privacy redacted 또는 aggregate를 사용하면 서버에서 나가는 정보의 범위가 제한됩니다.
- 검색 인덱스(Search index). Mac에서 구축되며, SQLite 체크포인트 API를 사용할 수 있는 경우
~/Library/Caches/imessage-mcp에 암호화되어 캐시되고, Messages 데이터베이스에서 파생된 키로 보호되므로 이미 메시지를 읽을 수 있는 앱만 열 수 있습니다. 삭제해도 항상 안전합니다. server_status는 검색이 메모리에서 계속되는 동안 사용 불가능하거나 실패한 캐시를 보고합니다.
- 신뢰할 수 없는 콘텐츠(Untrusted content). 메시지에는 AI를 조작하기 위해 작성된 텍스트가 포함될 수 있습니다. 서버는 클라이언트에게 모든 메시지 콘텐츠를 지침이 아닌 데이터로 취급하도록 알려줍니다.
자세한 내용은: SECURITY.md 및 PRIVACY.md.
개발(Development)
npm ci
npm test
npm run e2e
...
테스트는 합성 데이터만 사용합니다. CONTRIBUTING.md를 참조하십시오.
의존성 PR은 보호 자동 병합(protected auto-merge)을 사용합니다. 일일 상태 확인은 만료되는 자격 증명과 중단된 업데이트를 감지하며, 유지보수 및 복구를 참조하십시오.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
라이선스
MIT
