Skip to main content
Glama
deenesjakoruzh
wyattjoh

iMessage MCP

by wyattjoh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

iMessage MCP

macOS で iMessage にアクセスするためのパッケージを含む Deno モノレポ：

  • @wyattjoh/imessage - 読み取り専用の iMessage データベースアクセスのためのコアライブラリ

  • @wyattjoh/imessage-mcp - LLM 統合のための Model Context Protocol (MCP) サーバー

機能

  • テキスト内容、連絡先、または日付範囲でメッセージを検索

  • 最近のメッセージを取得

  • すべてのチャット/会話を一覧表示

  • すべての連絡先/ハンドルを取得

  • 特定のチャットからメッセージを取得

  • 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 日時文字列

    • endDate（任意）：終了日の ISO 日時文字列

    • 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）

    • ハンドルパラメータとして使用できる電話番号とメールアドレスを含む連絡先情報を返します

    • パフォーマンスと信頼性を向上させるため、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