Skip to main content
Glama
deenesjakoruzh
wyattjoh

iMessage MCP

by wyattjoh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

iMessage MCP

macOS에서 iMessage에 접근하기 위한 패키지들을 포함하는 Deno 모노레포입니다:

기능

  • 텍스트 내용, 연락처 또는 날짜 범위로 메시지 검색

  • 최근 메시지 가져오기

  • 모든 채팅/대화 목록 보기

  • 모든 연락처/핸들 가져오기

  • 특정 채팅에서 메시지 검색

  • iMessage 핸들 ID 연관과 함께 이름으로 macOS 연락처 검색

Related MCP server: imessage-mcp

요구 사항

  • macOS (iMessage는 macOS에서만 사용 가능)

  • Deno 2.x 이상

  • ~/Library/Messages/chat.db에 대한 읽기 권한, 또는 IMESSAGE_DB_PATH로 설정된 사용자 지정 데이터베이스에 대한 읽기 권한

  • ~/Library/Application Support/AddressBook/에 대한 읽기 권한 (연락처 검색용)

패키지

@wyattjoh/imessage

iMessage 데이터 접근을 위한 핵심 라이브러리:

deno add @wyattjoh/imessage
import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";

const db = await openMessagesDatabase();
const results = await searchMessages(db, { query: "hello" });
db.close();

전체 문서 보기

@wyattjoh/imessage-mcp

LLM 통합을 위한 MCP 서버:

# Run directly from JSR
deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp

# Or install globally
deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp

Claude Desktop 앱 통합을 위해 claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}

사용자 지정 메시지 데이터베이스

IMESSAGE_DB_PATH를 설정하여 chat.db의 주기적으로 새로 고쳐지는 스냅샷과 같은 다른 위치의 읽기 전용 SQLite 데이터베이스를 열 수 있습니다:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env=IMESSAGE_DB_PATH",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ],
      "env": {
        "IMESSAGE_DB_PATH": "/tmp/imessage-snapshot.sqlite"
      }
    }
  }
}

프로세스는 사용자 지정 파일에 대한 읽기 권한이 필요합니다. Deno가 IMESSAGE_DB_PATH를 읽을 권한이 없거나 변수가 비어 있거나 설정되지 않은 경우, 라이브러리는 환경 접근을 묻지 않고 ~/Library/Messages/chat.db를 사용합니다.

옵션 2: 소스에서 실행

  1. 이 저장소를 클론합니다

  2. 의존성을 설치합니다:

    deno cache src/index.ts

  3. 서버를 실행합니다:

    deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts
# Or use the task:
deno task start

사용 가능한 도구

  1. search_messages - 필터로 메시지 검색

    • query (선택): 검색할 텍스트

    • handle (선택): 필터링할 전화번호 또는 이메일

    • startDate (선택): 시작 날짜의 ISO datetime 문자열

    • endDate (선택): 종료 날짜의 ISO datetime 문자열

    • limit (선택): 최대 결과 수 (1-200, 기본값: 100)

    • offset (선택): 페이지네이션 오프셋 (기본값: 0)

  2. get_recent_messages - 가장 최근 메시지 가져오기

    • limit (선택): 메시지 수 (1-100, 기본값: 20)

    • offset (선택): 페이지네이션 오프셋 (기본값: 0)

  3. get_chats - 모든 대화 목록 보기

    • limit (선택): 채팅 수 (1-200, 기본값: 50)

    • offset (선택): 페이지네이션 오프셋 (기본값: 0)

  4. get_handles - 모든 연락처/핸들 가져오기

    • limit (선택): 핸들 수 (1-200, 기본값: 100)

    • offset (선택): 페이지네이션 오프셋 (기본값: 0)

  5. get_messages_from_chat - 특정 채팅에서 메시지 가져오기

    • chatGuid (필수): 채팅 GUID

    • limit (선택): 메시지 수 (1-200, 기본값: 50)

    • offset (선택): 페이지네이션 오프셋 (기본값: 0)

  6. search_contacts - 이름으로 macOS 연락처를 검색하고 전화번호 가져오기

    • firstName (필수): 검색할 이름 (예: 'John')

    • lastName (선택): 검색할 성 (예: 'Smith'). 생략하면 모든 이름 필드에서 검색합니다

    • limit (선택): 최대 결과 수 (1-200, 기본값: 50)

    • offset (선택): 페이지네이션 오프셋 (기본값: 0)

    • handle 매개변수로 사용할 수 있는 전화번호와 이메일 주소가 포함된 연락처 정보를 반환합니다

    • 더 나은 성능과 안정성을 위해 macOS AddressBook 데이터베이스에서 직접 검색합니다

페이지네이션 예시

모든 도구는 이제 limit 및 offset 매개변수를 사용한 페이지네이션을 지원하며 페이지네이션 메타데이터를 반환합니다:

// Get first 20 recent messages
get_recent_messages({ limit: 20, offset: 0 });

// Get next 20 recent messages (page 2)
get_recent_messages({ limit: 20, offset: 20 });

// Get first 10 chats
get_chats({ limit: 10, offset: 0 });

// Get messages 51-100 from a specific chat
get_messages_from_chat({
  chatGuid: "iMessage;-;+15551234",
  limit: 50,
  offset: 50,
});

// Search with pagination
search_messages({
  query: "meeting",
  limit: 100,
  offset: 200,
});

// Search contacts with pagination
search_contacts({
  firstName: "John",
  lastName: "Smith",
  limit: 50,
  offset: 0,
});

페이지네이션 메타데이터가 포함된 응답 형식

모든 페이지네이션 도구는 이제 다음 형식으로 응답을 반환합니다:

{
  "data": [
    // Array of results (messages, chats, handles, etc.)
  ],
  "pagination": {
    "total": 1250, // Total number of results available
    "limit": 100, // Current page size
    "offset": 200, // Current offset
    "hasMore": true, // Whether there are more results to fetch
    "page": 3, // Current page number (1-indexed)
    "totalPages": 13 // Total number of pages
  }
}

이 메타데이터는 다음에 도움이 됩니다:

  • 모든 결과를 가져오지 않고도 총 결과 수를 알 수 있습니다

  • 더 가져올 페이지가 있는지 확인할 수 있습니다 (hasMore)

  • 현재 페이지와 전체 페이지 수를 계산할 수 있습니다

  • 적절한 페이지네이션 UI 구성 요소를 만들 수 있습니다

보안 참고 사항

  • 이 서버는 iMessage 데이터베이스에 대한 읽기 전용 접근 권한으로 실행됩니다

  • 메시지를 보내거나 수정할 수 없습니다

  • 서버는 로컬 데이터에만 접근합니다

개발

이것은 Deno 워크스페이스 모노레포입니다. 루트에서 실행되는 모든 명령은 모든 패키지에 영향을 미칩니다.

# Clone the repository
git clone https://github.com/wyattjoh/imessage-mcp.git
cd imessage-mcp

# Cache dependencies
deno cache packages/*/mod.ts

# Format all code
deno task fmt

# Lint all packages
deno task lint

# Type check all packages
deno task check

# Run tests
deno task test

# Run MCP server locally
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

# Publish packages (CI/CD)
deno publish

개별 패키지 작업

# Work on @wyattjoh/imessage
cd packages/imessage
deno test --allow-read --allow-env --allow-ffi --allow-sys=homedir

# Work on @wyattjoh/imessage-mcp
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

라이선스

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • iMessage MCP

    4ndylg
    A
    license
    Not graded
    quality
    D
    maintenance
    Read-only MCP server for local macOS Messages database, enabling querying of chats, messages, attachments, and metadata.
    246 npm
    MIT

  • imessage-mcp-server

    tinyxia
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for reading and sending iMessages on macOS. Exposes iMessage history and send capabilities through tools like list_conversations and send_imessage.
    6 npm
    MIT