mcpField
I
imessage-max

imessage-max

ローカル
github.com/cyberpapiiiコミュニケーション62 週間前に更新

imessage-max について

iMessage Maxは、macOS上でiMessageの会話を読み取り、検索、送信するSwift製MCPサーバーです。意図に沿ったツールにより、データベーステーブルを直接扱わずに、エージェントがチャットや添付ファイルを操作できます。

主な機能

  1. 01連絡先・名前・内容からチャットを検索
  2. 02メッセージの取得と絞り込み
  3. 03メッセージ検索と前後の文脈取得
  4. 04Contactsによる電話番号の名前解決
  5. 05画像添付ファイルの一覧と取得
  6. 06指定したチャットへのメッセージ送信

活用シーン

  1. 01連絡先との会話を探して確認
  2. 02話題を検索し関連する前後のメッセージを確認
  3. 03未読や最近活発な会話を確認
  4. 04共有画像を探して取得

MCP 対応

stdioとHTTP経由でiMessage操作をMCPツールとして公開し、新旧のプロトコルネゴシエーションに対応します。ツールのみを実装し、プロンプトやリソースは提供しません。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"cyberpapiii-imessage-max": {
"command": "uvx",
"args": [
"imessage-max"
]
}
}
}
起動コマンドuvx imessage-max

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
pypiimessage-max0.4.4

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

iMessage Max

iMessage Max

iMessage 用の MCP(Model Context Protocol)サーバーです。AI エージェントがメッセージを読み取り、検索、送信できます。その際、電話番号を連絡先名に解決します。

Swift で書かれています。バイナリは 1 つで、実行時の依存関係はありません。

配布方法

Swift による 1 つの実装を swift/ に用意し、以下の方法で配布しています。

  • GitHub リリース(arm64、アドホック署名済み)
  • Homebrew(cyberpapiii/tap)
  • ソースからのビルド
  • Codex プラグインのメタデータ(.codex-plugin/)
  • Claude Desktop MCPB のメタデータ(mcpb/)

機能

  • データベースのテーブルではなく、実際にユーザーが尋ねる質問を中心に設計された 13 個のツール
  • macOS の連絡先を使って電話番号を名前に解決
  • 画像の 3 つのバリエーション:ビジョン用(1568px)、サムネイル(400px)、フルサイズ(オリジナル)。写真を必ずフルサイズで取得する必要はありません
  • メッセージをセッションにまとめ、4 時間以上の間隔がある箇所で区切ります
  • 添付ファイルの一覧で、各ファイルがディスク上にあるか、iCloud にオフロードされているかを表示
  • 生の SQLite3 と Core Image による GPU アクセラレーション
  • chat.db のみを読み取ります。送信には Messages.app のオートメーション権限が必要です

このプロジェクトを作った理由

多くの iMessage ツールはデータベースの生の構造を公開するため、ユーザーの意図を満たすのに 3~5 回のツール呼び出しが必要です。この MCP は、ユーザーの意図に沿ったツールを提供します。

"What did Contact A and I talk about yesterday?"
→ find_chat(participants=["Contact A"]) + get_messages(since="yesterday")

"Show me the exact details for this thread before I reply"
→ get_chat_details(chat_id="chat123")

"Show me photos from the group chat"
→ list_attachments(chat_id="chat123", type="image")

"Find where we discussed the launch timeline"
→ search(query="launch timeline")

エージェントによくあるワークフロー

エージェントがツールを単発で呼び出すのではなく、短いワークフローとして使うと、最も効果を発揮します。

エージェントは、chat123 のような chat_id 値を、ツール呼び出しや宛先を正確に指定した送信に使う内部ハンドルとして扱ってください。結果を人に説明するときは、「チャット 123」と言うのではなく、返されたチャット名、グループ名、または参加者から導き出されたラベルを使ってください。

適切な会話を見つけてから、内容を読む
find_chat(participants=["Contact A"])
get_chat_details(chat_id="chat123")
get_messages(chat_id="chat123", since="yesterday", limit=50)

スレッド ID の正確さより相手が重要な場合に使います。

まず検索し、それから詳しく調べる
search(query="launch timeline", limit=10)
get_context(message_id="msg_456", before=5, after=10)

話題はわかっていても、どこで話されたかがわからない場合に使います。

対応が必要な項目を確認する
get_unread()
get_active_conversations(hours=24, min_exchanges=2)

チャット一覧を広く確認した後、未読スレッドやアクティブな会話を見つけるために使います。

添付ファイルを安全に扱う
list_attachments(chat_id="chat123", type="image", since="30d")
get_attachment(attachment_id="att123", variant="vision")

list_attachments を使って、ファイルが共有されたメッセージを見つけます。正確な添付ファイル ID と、各ファイルがディスク上にあるかどうかが返されるため、取得する前に確認できます。

正確な宛先指定が重要な場合は、送信先を厳密に指定する
find_chat(participants=["Contact A", "Contact B"])
send(chat_id="chat456", text="Please use the latest draft")

慎重な送信では、まず対象のチャットを正確に特定してから chat_id を使い、意図したスレッドにメッセージが届くようにしてください。

インストール

Homebrew(推奨)
brew tap cyberpapiii/tap
brew install imessage-max
ソースから
git clone https://github.com/cyberpapiii/imessage-max.git
cd imessage-max/swift
swift build -c release

# Binary is at .build/release/imessage-max

ローカル開発、高度なセットアップ、署名済みインストールの手順については、以下を参照してください。

プロトコルのサポート

iMessage Max は、2 つの時代の仕様に対応する MCP サーバーです。両方のトランスポート(stdio と HTTP)が、リクエストごとに選択される両方の仕様に同時に対応します。

時代リビジョンライフサイクル選択方法
モダン2026-07-28ステートレス、リクエストごとの _metaリクエストの _meta 内の io.modelcontextprotocol/protocolVersion(または server/discover)
レガシー2025-03-26 … 2025-11-25initialize + セッションinitialize リクエスト / Mcp-Session-Id

モダンなクライアントは server/discover で対応状況を確認し、HTTP 経由で必須の MCP-Protocol-Version、Mcp-Method、および(tools/call の場合は)Mcp-Name ヘッダーを送信します。レガシーなクライアントは変更なしで引き続き動作します。クライアントの移行は不要で、実際のクライアントが依存する限り、レガシーサポートを継続します。

このサーバーが実装するのはツールのみです。意図的に、プロンプト、リソース、補完、サブスクリプション、タスク、MRTR フローは備えていません。公式の適合性テストスイートは、docs/conformance-baseline.yml に記載されたベースラインで両方の時代に対して実行されます。

クライアントアイコンのメタデータ

iMessage Max には、MCP プロトコルの主要なサーフェスと、独自のメタデータを使用するクライアントのパッケージングサーフェス向けのアイコンが含まれています。

  • MCP 2025-11-25 の初期化レスポンスには、PNG の serverInfo.icons が含まれます。
  • 各ツールは、コンパクトな PNG ツールアイコンを公開します。
  • Codex プラグインのメタデータは .codex-plugin/plugin.json にあり、assets/codex/icon.png と assets/codex/logo.png を使用します。
  • Claude Desktop/MCPB のメタデータは mcpb/manifest.json にあり、mcpb/assets/ 配下の PNG アセットを使用します。

コミット済みの PNG ソースセットは assets/icons/ にあり、サイズは 16x16、32x32、64x64、128x128、256x256、512x512 です。

セットアップ

1. フルディスクアクセスを許可する

~/Library/Messages/chat.db を読み取るために必要です。

  1. 「システム設定」→「プライバシーとセキュリティ」→「フルディスクアクセス」を開きます
    • をクリックしてバイナリを追加します

Homebrew でインストールした場合、バイナリは /opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max にあります(/opt/homebrew/bin/ にあるシンボリックリンクではありません)。次のコマンドで確認できます。

# Open the folder containing the actual binary
open $(dirname $(readlink -f $(which imessage-max)))

ソースからビルドした場合は、クローンしたディレクトリにある .build/release/imessage-max を追加します。 許可を変更した後はサーバーを再起動してください。macOS では、変更後に起動したプロセスにのみフルディスクアクセスが適用されます。

ファイルピッカーで ⌘+Shift+G を押してパスを貼り付けると、直接その場所に移動できます。

2. 連絡先へのアクセスを許可する

電話番号を名前に対応付けるために必要です。サーバーがアクセスを要求するのはターミナルから起動した場合のみです。launchd と MCP クライアントはヘッドレスで起動するため、ヘッドレスプロセスはアクセス許可を求めることがありません。ターミナルから imessage-max --request-contacts-access を実行して一度アクセスを許可し、その後サービスを再起動してください。--contacts-policy request|skip(または IMESSAGE_MAX_CONTACTS_POLICY)を指定すると、ターミナルの検出結果が上書きされます。

手動で設定する場合は、「システム設定」→「プライバシーとセキュリティ」→「連絡先」で imessage-max を追加します。

3. MCP クライアントを設定する

MCP クライアントのサーバー設定に imessage-max を追加します。

多くの MCP クライアントでは、次のような JSON 構造を使用します。

Homebrew の場合:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max"
    }
  }
}

ソースからビルドした場合:

{
  "mcpServers": {
    "imessage": {
      "command": "/path/to/imessage-max/swift/.build/release/imessage-max"
    }
  }
}

クライアントの設定形式が異なる場合は、同じバイナリパスを指定してください。

4. MCP クライアントを再接続する

設定を保存した後、MCP クライアントを再接続するか、再起動してください。サーバーが利用可能なツールに表示されます。diagnose を実行して接続を確認できます。

ツール

find_chat

参加者、名前、または最近の内容からチャットを検索します。

デフォルトでは、Messages.app が「不明な差出人」または「迷惑メッセージ」に振り分けたチャットは非表示になります。レスポンスには、この表示からフィルターで除外されたチャットの数を示す filtered_hidden が含まれます。include_filtered=True を渡すと、それらのチャットも表示できます。

find_chat(participants=["Contact A"])              # Find a direct chat
find_chat(participants=["Contact A", "Contact B"]) # Find a group with both
find_chat(name="Project Group")                    # Find by chat name
find_chat(contains_recent="latest draft")          # Find by recent content
find_chat(name="Project Group", include_filtered=True)  # Also search junk / unknown-sender chats
get_chat_details

会話全体を開かずに、既知のスレッドを確認します。

get_chat_details(chat_id="chat123")                          # Participants, handles, state, last message
get_chat_details(chat_id="chat123", include_shared_summary=false) # Skip recent shared summary
get_messages

柔軟なフィルタリングでメッセージを取得します。メディアのメタデータを返します。明示的に指定した chat_id による検索はフィルターの対象になりません。

get_messages(chat_id="chat123", limit=50)           # Recent messages
get_messages(chat_id="chat123", since="24h")        # Last 24 hours
get_messages(chat_id="chat123", from_person="Contact A")  # From specific person
get_messages(chat_id="chat123", has="links")        # Messages that contain a URL

has は、コンテンツの種類(links、attachments、images)でフィルタリングします。links には、Messages が URL プレビューの吹き出しとして保存するリンクメッセージが含まれます(macOS 26 で一般的なケースです)。

グループのシステムメッセージ(名前の変更、メンバーの追加または削除、退出)は、text: null と event オブジェクトを含む形で返されます。 {"type": "rename", "title": "Trip"}、{"type": "participant_added", "participant": "Alice"}、 {"type": "participant_removed", ...}、{"type": "left"}、またはサーバーが名前を付けていないイベントの種類については {"type": "other", "item_type": N} が返されます。チャットのプレビューでは、これらのイベントが同じ内容を表す言葉で説明されます(「グループ名を Trip に変更しました」など)。

リアクション、返信、編集:各メッセージには、reactions(標準のタップバックでは ["❤️ alice"]。カスタム絵文字では絵文字そのもの、ステッカーによるリアクションでは 🩵 sticker トークン)、reply_to(元のメッセージの msg_<rowid>)、reply_count、edited: true が含まれることがあります。削除されたタップバックは省略されます。4 つのフィールドはいずれも任意で、値が空の場合は省略されます。search と get_context にも同じ 4 つのフィールドが含まれます。これらは読み取り専用です。サーバーは送信できないため、diagnose では引き続き tapbacks と edit_unsend が unsupported と報告されます。

get_messages_since

すべてのチャットで、ROWID カーソル以降に届いた新しいメッセージを到着順に取得します。返された next_rowid を since_rowid として渡すと、ページ取得やポーリングができます。消費済みの行(リアクション、フィルタリングされたチャット、孤立した行)がカーソルを進めるため、next_rowid は最後に返されたメッセージの rowid より大きい場合があります。現在のカーソルだけを取得するには、since_rowid を省略します。カーソルはこの Mac の chat.db に対してのみ有効です。

get_messages_since()                          # Current cursor only
get_messages_since(since_rowid=234000)        # Messages after that row
get_messages_since(since_rowid=234000, limit=50)
get_messages_since(since_rowid=234000, chat_id="chat123")
get_messages_since(since_rowid=234000, include_filtered=True)
パラメーター型デフォルト意味
since_rowidinteger省略排他的な ROWID カーソルです。省略するか、現在のカーソルのみを取得するには -1 を渡します。
chat_idstring省略1 つのチャットに絞り込みます(chat123 または 123)。
limitinteger100返すメッセージの最大数(1~500)です。
include_filteredbooleanfalse迷惑メッセージ/不明な送信者のチャットを含めます。
include_reactionsbooleantrue返されるメッセージにリアクション文字列を付加します。

レスポンス例:

{
  "since_rowid": 234000,
  "messages": [
    {
      "id": "msg_234001",
      "rowid": 234001,
      "chat": {"id": "chat12", "name": "Alice Smith"},
      "from": "Alice Smith",
      "text": "on my way",
      "ts": "2026-09-02T15:00:00Z"
    },
    {
      "id": "msg_234010",
      "rowid": 234010,
      "chat": {"id": "chat40", "name": "Weekend"},
      "from": "me",
      "text": "see you there",
      "ts": "2026-09-02T15:01:00Z"
    }
  ],
  "next_rowid": 234050,
  "has_more": false,
  "current_rowid": 234050,
  "stalled": false,
  "filtered_hidden": 1
}

ポーリング手順:最初は since_rowid を指定せずに呼び出し、next_rowid を保存してから、任意の間隔でその値を指定して呼び出します。stalled が true の場合は、約 1 秒待って同じカーソルで再試行します。next_rowid をメッセージ ID と比較しないでください。

get_attachment

添付ファイル ID を指定して、解像度のバリエーションから画像コンテンツを取得します。

get_attachment(attachment_id="att123")                 # Default: vision (1568px)
get_attachment(attachment_id="att123", variant="thumb") # Quick preview (400px)
get_attachment(attachment_id="att123", variant="full")  # Original resolution
バリエーション解像度用途トークンコスト
vision(デフォルト)1568pxAI 分析、OCR約1,600トークン
thumb400px簡易プレビュー約200トークン
fullオリジナル最大限の詳細変動
list_chats

プレビュー付きで最近のチャットを一覧表示します。

デフォルトでは、Messages.app が「不明な送信者」または「迷惑メッセージ」に振り分けたチャットは非表示です。レスポンスにはフィルターで除外されたチャット数が filtered_hidden として含まれます。これらを表示するには include_filtered=True を渡します。

list_chats(limit=20)          # Recent chats
list_chats(is_group=True)     # Only group chats
list_chats(since="7d")        # Active in last week
list_chats(include_filtered=True)   # Also show junk / unknown-sender chats
search

メッセージを全文検索します。

デフォルトでは、迷惑メッセージと不明な送信者のチャットは非表示です。レスポンスには filtered_hidden が含まれます。これらも検索するには include_filtered=True を渡します。

search(query="draft")                           # Search all messages
search(query="budget", from_person="Contact A") # From specific person
search(query="launch", is_group=True)           # Only in group chats
search(query="draft", include_filtered=True)    # Also search junk / unknown-sender chats
get_context

特定のメッセージの前後にあるメッセージを取得します。

get_context(message_id="msg_123", before=5, after=10)
get_active_conversations

最近やり取りのあったチャットを検索します。

get_active_conversations(hours=24)
get_active_conversations(is_group=True, min_exchanges=3)
list_attachments

メッセージごとにグループ化して共有アイテムを一覧表示します。各行には、後で取得するための正確な添付ファイル ID が含まれます。

list_attachments(type="image", since="7d")
list_attachments(chat_id="chat123", type="any")

Messages で非表示にされる添付ファイル(リンクプレビューのペイロードなどの hide_attachment)は一覧に表示されませんが、get_attachment では ID を指定して取得できます。

get_unread

未読のスレッドまたは未読メッセージを取得します。デフォルトではチャットごとの概要を返します。

デフォルトでは、迷惑メッセージと不明な送信者のチャットは非表示です。レスポンスには filtered_hidden が含まれます。これらを含めるには include_filtered=True を渡します。

get_unread()                         # Summary by chat for last 7 days
get_unread(since="24h")              # Summary by chat for last 24 hours
get_unread(format="messages")        # Row-level unread messages
get_unread(include_filtered=True)    # Also show junk / unknown-sender chats
send

メッセージまたはファイル添付を送信します(Messages.app のオートメーション権限が必要です)。

send(to="Contact A", text="Checking in")
send(chat_id="chat123", text="Please use the latest draft")
send(chat_id="chat123", file_paths=["/path/save-the-date.jpg"])
send(to="Contact A", file_paths=["/path/reference.png"], text="Sharing the file here")

ルール:

  • to または chat_id のいずれか 1 つだけを指定します。
  • text または file_paths の少なくとも 1 つを指定します。
  • 両方を指定した場合、ファイルを先に送信し、テキストを最後に送信します。

添付ファイルのパスは絶対パス(または ~/ で始まるパス)で指定する必要があります。パスは各コンポーネントごとに確認され、いずれかの部分がシンボリックリンクの場合は拒否されます(/tmp、/var、/etc は許可され、/private/... として読み取られます)。リンクをたどらずにファイルを開き、通常のファイルであることを確認したうえで、開いたファイルハンドルから ~/Pictures/imessage-max-staging/ 配下の非公開 0700 ディレクトリにコピーします。Messages から見えるのはコピーだけです。お使いの Mac で ~/Pictures 自体がシンボリックリンクの場合、実際のディレクトリを指すようになるまで、ファイル付きの send はステージングを拒否します。

diagnose

設定と権限に関する問題をトラブルシューティングします。

diagnose()  # Returns: database status, contacts count, permissions, capabilities

capabilities.verified_send は、chat.db を読み取り可能で Messages Automation が正常な場合は supported、データベースは読み取り可能でも Automation が正常でない場合は degraded、データベースを読み取りできない場合は permission-gated になります。

database.features には、この Mac に存在する chat.db のオプション列が table.column 形式で一覧表示されます(例:message.date_edited)。値が false の場合、それを読み取るツールは失敗せずに機能が制限されます。message.thread_originator_guid がない場合は reply_to や reply_count が、message.date_edited がない場合は edited が、message.associated_message_emoji がない場合はカスタム絵文字リアクションのテキストが利用できません。

contacts.status は、authorized、limited、denied、restricted、not_determined、not_requested_headless、skipped_ci、または <status>_load_failed のいずれかです。プロンプトをスキップしたヘッドレスプロセスでは not_requested_headless が報告され、修正方法として --request-contacts-access が示されます。

リリース前の確認

リリース前に、次の項目を確認してください。

送信に関する補足:

  • 送信先が正確に特定できる場合、送信は直ちに実行されます。確認ゲートはありません。送信先が曖昧な場合は status: "ambiguous" で拒否されます。confirm パラメーターは非推奨であり、無視されます(互換性のためにのみ保持されています)。認可はユーザーとエージェントの会話、およびクライアントのツール承認 UI で行われ、サーバー側では行われません。

送信結果の意味(テキスト送信は送信後に chat.db と照合して検証されます):

  • status: "confirmed" は、検証期間内に chat.db で送信メッセージの行がエラーなしで見つかったことを意味します。verified_message_guid が証拠となります。これは配信確認ではありません。
  • status: "uncertain" は、トランスポートが送信を受け付けたものの、ポーリング期間内に行が見つからなかったことを意味します。get_messages で確認してください。
  • status: "mismatch" は、意図したものとは異なるチャットにメッセージが届いたことを意味します。成功として扱わないでください。
  • status: "failed_delivery" は、配信エラーが記録されたメッセージ行が見つかったことを意味します。メッセージは配信されていません。verified_message_guid とエラーコードが証拠となります。
  • status: "partial_failure" は、複数ペイロードの送信で、一部のペイロードを送信した後に後続のペイロードが失敗したことを意味します。message に送信された内容と失敗した内容が記載されます。失敗したペイロードのみを再試行し、呼び出し全体は再試行しないでください。
  • status: "sent" は、検証を利用できなかった(DB を読み取れなかった)ことを意味します。トランスポートが送信を受け付けたことのみを示します。
  • status: "pending_confirmation" は、Messages が添付ファイルの送信を受け付けたものの、ポーリング期間内にファイル転送の完了を確認できなかったことを意味します。
  • status: "failed" は、送信に失敗したことを意味します。
  • status: "ambiguous" は、対象を安全に特定できなかったことを意味します。
Disposition と retry_safe

すべての send レスポンスには、disposition と retry_safe も含まれます。disposition はトランスポート(Apple イベントが送信されたかどうか)に関するもので、status は chat.db に関するものです。

statusdispositionretry_safe
confirmed, uncertain, mismatch, sentcompletedfalse
failed_deliverycompletedtrue
pending_confirmationmay_have_completedfalse
failed(トランスポート)send の結果not_started の場合のみ true
failed(検証/解決)not_startedtrue
partial_failure失敗したペイロードの dispositionfalse
ambiguousnot_startedtrue
{"status":"failed","disposition":"not_started","retry_safe":true,"error":"Could not find chat 'iMessage;-;does-not-exist' in Messages.app."}
{"status":"failed","disposition":"may_have_completed","retry_safe":false,"error":"Send operation timed out. Messages.app may be unresponsive."}

注:

  • pending_confirmation は通常の非致命的な添付ファイルの状態であり、完全な失敗とは異なります
  • チャットを指定した送信では、chat_id で識別される既存の会話が対象になります
  • JSON 形式のツールは、古いクライアント向けの従来のテキストコンテンツに加えて、MCP の structuredContent も返します

例:

  • {"status":"confirmed","verified_message_guid":"...",...} は、chat.db で配信が確認されたことを意味します
  • {"status":"pending_confirmation","success":false,...} は、Messages が添付ファイルを受け付けたものの、MCP がまだ完了を最終確認できていないことを意味します

トラブルシューティング

連絡先が電話番号で表示される

diagnose を実行し、contacts.status を確認してください。denied または not_determined の場合:

  • imessage-max バイナリを「システム設定」→「プライバシーとセキュリティ」→「連絡先」に追加します

diagnose が contacts.status: "not_requested_headless" を報告した場合は、ターミナルから imessage-max --request-contacts-access を実行してください。連絡先を変更すると 30 秒以内に名前が更新され、アクセス権が取り消されるとすぐに名前は表示されなくなります。再起動は不要です。

「iMessage データベースを読み取れません」/permission_denied

chat.db を開くプロセスにフルディスクアクセスがありません。launchd サービスの場合は imessage-max バイナリ自体、stdio クライアントの場合はそれを起動するアプリが該当します。diagnose を実行してください。database.fix に実行ファイルと手順が表示されます。

  1. 「システム設定」→「プライバシーとセキュリティ」→「フルディスクアクセス」で、該当する実行ファイル(またはそれを起動するアプリ)を追加します。
  2. すでに表示されている場合は、いったんオフにしてからオンにします。以前のコード署名に紐づいた権限は、付与済みのように表示されても機能しません。make setup-signing を実行すると、バイナリに安定した ID が付与され、再ビルド後も維持されます。
  3. 権限は新たに起動したプロセスにのみ適用されます。次のいずれかを実行して再起動します。 launchctl kickstart -k gui/$(id -u)/local.imessage-max または cd swift && make restart
  4. ターミナルから切り分けます:sqlite3 -readonly ~/Library/Messages/chat.db 'pragma quick_check;'。 ok が表示された場合、ターミナルにはアクセス権がありますが、サーバープロセスにはありません。 unable to open database file が表示された場合、ユーザーに対する権限が不足しています。

make install は、HTTP 経由で diagnose を呼び出し、database.accessible が false の場合に失敗する make verify-db で終了するようになりました。フルディスクアクセスを変更した後は、次のコマンドを単独で実行してください。

cd swift && make verify-db
「データベースが見つかりません」エラー

~/Library/Messages/chat.db が存在しません。iMessage にサインインし、メッセージを 1 件送信または受信してください。

画像に「attachment_offloaded」エラーが表示される

一部の添付ファイルはディスク上ではなく、iCloud に保存されています。list_attachments には、各ファイルの available: true/false を含むネストされた添付ファイルの概要が表示されます。オフロードされた添付ファイルをダウンロードするには、Messages.app で会話を開いてください。

MCP クライアントがサーバーを読み込まない
  1. 設定ファイルの構文が有効な JSON であることを確認します
  2. バイナリのパスが正しいことを確認します
  3. MCP クライアントを再接続するか、完全に再起動します

アーキテクチャ

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP Client /   │◄───►│  iMessage Max   │◄───►│  chat.db        │
│  Agent          │     │  (Swift MCP)    │     │  (SQLite)       │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │  Contacts.app   │
                        │  (CNContactStore)│
                        └─────────────────┘

要件

  • macOS 15 以降(Sequoia 以降)
  • フルディスクアクセス権限
  • 連絡先の権限(名前の解決に必要)
  • Messages.app のオートメーション権限(送信のみ)

高度なセットアップ

HTTP モード、ローカルバックグラウンドサービスのセットアップ、開発コマンド、コントリビューター向けのワークフローの詳細については、Swift README を参照してください。リクエストボディは 30 秒以内に受信する必要があります。アップロードが停止した場合は、JSON-RPC エラーボディとともに HTTP 408 が返され、60 秒間アイドル状態の接続は閉じられます。以下も参照してください。

ライセンス

MIT

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。