mcpField
M
Mac Messages MCP

Mac Messages MCP

ローカル
pypi.orgコミュニケーション3382 日前に更新

Mac Messages MCP について

Mac Messages MCP は、ローカルの Mac 上で動作し、macOS のメッセージ App のメッセージを読み取り・検索・送信する MCP サーバーです。メッセージと連絡先のデータベースは読み取り専用で開き、クライアントが送信ツールを明示的に呼び出した場合のみ送信します。Claude や Cursor から iMessage を扱いたいユーザー向けです。

主な機能

  1. 01連絡先や期間で絞り込む最近のメッセージ読み取り
  2. 02メッセージ本文のあいまい検索
  3. 03未読数付きの会話一覧表示
  4. 04Messages.app経由のメッセージと添付ファイルの送信
  5. 05名前による連絡先と電話番号の検索

活用シーン

  1. 01直近2時間の未読メッセージの要約
  2. 02特定の連絡先との過去のメッセージ検索
  3. 03ユーザー確認後の返信の下書きと送信

MCP 対応

本プロジェクトは、メッセージの読み取り・検索・連絡先検索・送信のツールを MCP クライアントに提供し、関連するリソースとプロンプトも公開する MCP サーバーです。

設定

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

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ

ツール

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

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

詳細

Mac Messages MCP

macOS のメッセージを、あらゆるローカル MCP クライアントから読み取り、検索、送信できます。

PyPI Python CI Downloads macOS License: MIT

クイックスタート · 利用可能なツール · エージェントスキル · コマンドラインインターフェイス · セキュリティ · 変更履歴

Claude、Codex、Cursor、VS Code、またはあらゆるローカル MCP クライアントを使って、macOS のメッセージアプリからメッセージを検索、読み取り、送信できます。

Mac Messages MCP は Mac 上でローカルに動作します。メッセージと連絡先のデータベースを読み取り専用で開き、クライアントから要求されたデータのみを返します。また、クライアントが送信ツールを明示的に呼び出した場合に限り、Messages.app の自動操作を使用します。

重要

このサーバーは macOS 専用です。メッセージの読み取りにはフルディスクアクセスが必要です。送信には、Messages にサインインした Mac と、起動アプリに Messages の自動操作を許可する権限が必要です。

仕組み

flowchart LR
    A[MCP client] -->|stdio| B[mac-messages-mcp]
    B --> C{Tool call}
    C -->|read tools| D[(chat.db read-only)]
    C -->|read tools| E[(AddressBook read-only)]
    C -->|send tools| F[Messages.app]
    F --> G[Recipient]
    D --> H[Untrusted-output boundary]
    E --> H
    H --> A

クライアントが読み取るデータはすべて、読み取り専用で開かれたローカルの SQLite データベースから取得されます。マシンの外部に送信されるものはすべて、明示的な送信ツール呼び出しのもと、Messages.app を通じて送信されます。メッセージや連絡先に由来するテキストは、モデルに返す際に信頼できないデータとして区分されます。

機能

項目Mac Messages MCP が提供する機能
読み取りすべての会話、または連絡先、グループチャット、日付範囲、未読状態で絞り込んだ最近のメッセージ。limit/offset によるページングと、前方カーソルを使った読み取り
会話種類、メッセージ数と未読数、最終アクティビティを含むすべての会話(1 対 1、ビジネス、グループ)と、新着メッセージを待つブロッキング待機
検索期間または全履歴を対象としたメッセージ本文のあいまい検索。連絡先または会話による絞り込み
コンテキストメッセージごとのサービス(iMessage/SMS/RCS)、未読状態と配信状態、タップバック、スレッド形式の返信
連絡先おおよその名前によるあいまい検索、送信に使える電話番号、連絡先の作成
グループチャット名前付きグループチャットの検出と、読み取りや送信で再利用できる安定したチャット ID
送信SMS/RCS へのフォールバックに対応した iMessage、ファイル添付、MCP エリシテーションによる任意の人間の承認、iMessage の到達可能性チェック
スケジュールサーバープロセスの稼働中に、後で配信するメッセージをキューに登録
添付ファイルメタデータ検索、テキスト/PDF の内容検索(ベストエフォート)、インライン画像(HEIC を PNG に変換)、大きなファイルや画像以外のファイルのローカルパス
診断MCP クライアント内からのメッセージおよび連絡先データベースの権限チェック
プライバシー読み取り専用の SQLite アクセス、独自のメッセージアーカイブなし、構造化された信頼できない出力の境界

クイックスタート

1. uv をインストール
brew install uv

ランチャーが利用できることを確認します。

uvx --version

Python 3.10 以降が必要です。uvx は互換性のある Python を用意し、Mac Messages MCP を隔離環境にインストールするため、事前に仮想環境を作成する必要はありません。

2. macOS の権限を許可する

システム設定 → プライバシーとセキュリティ → フルディスクアクセスを開き、MCP サーバーを起動するアプリを有効にします。

  • Claude Desktop、Cursor、VS Code、またはそのアプリで設定する場合は ChatGPT デスクトップアプリ
  • Claude Code または Codex CLI をターミナルから使用する場合は Terminal、iTerm2、Ghostty、または別のターミナル

フルディスクアクセスを変更した後は、アプリを終了して再度開いてください。初回の連絡先検索または送信時に、macOS から連絡先へのアクセスやメッセージを操作する権限を個別に求められる場合があります。これらの確認には許可してください。

また、Messages.app が開いており、サインイン済みで、通常のメッセージを送信できる状態であることを確認してください。

3. MCP クライアントにサーバーを追加する

サーバーコマンドはどの環境でも同じです。

uvx mac-messages-mcp

以下からクライアントを選択してください。

Claude Desktop

Claude → 設定 → 開発者 → 設定を編集を開き、次を追加します。

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

claude_desktop_config.json にすでに設定されている他のサーバーはそのまま残し、ファイルを保存して Claude Desktop を再起動してください。

Claude Desktop は、インストール可能な .mcpb 拡張機能にも対応しています。このリポジトリを拡張機能としてパッケージ化する場合は、Claude Desktop 拡張機能をビルドするを参照してください。

Claude Code

すべてのプロジェクトで使えるよう、ユーザースコープで一度追加します。

claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp

次のコマンドで確認します。

claude mcp get mac-messages

Claude Code 内で /mcp を実行すると、接続とツールを確認できます。

Codex CLI、Codex IDE 拡張機能、ChatGPT デスクトップアプリ

同じ Mac 上の Codex クライアントは、MCP の設定を共有します。次のコマンドでサーバーを追加します。

codex mcp add mac-messages -- uvx mac-messages-mcp

次に、次のコマンドで確認します。

codex mcp list

~/.codex/config.toml に直接追加することもできます。

[mcp_servers.mac-messages]
command = "uvx"
args = ["mac-messages-mcp"]

設定を変更した後は、デスクトップアプリまたは IDE 拡張機能を再起動してください。Codex CLI では、/mcp を使うと有効なサーバーを確認できます。

Cursor

MCP サーバーをインストール

または、Cursor の設定 → ツールと MCP → 新しい MCP サーバーを開き、次を使用します。

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

保存した後、Cursor の MCP 設定からサーバーを再起動してください。

VS Code / GitHub Copilot

コマンドパレットを開き、MCP: サーバーを追加を実行します。**コマンド(stdio)**を選択し、コマンドに uvx を入力し、引数として mac-messages-mcp を追加して、グローバルにインストールします。

または、ターミナルから追加します。

code --add-mcp '{"name":"mac-messages","command":"uvx","args":["mac-messages-mcp"]}'

同等のユーザーまたはワークスペースの mcp.json エントリは次のとおりです。

{
  "servers": {
    "mac-messages": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

メモ

VS Code ではトップレベルの servers オブジェクトを使用します。Claude Desktop と Cursor では mcpServers を使用します。

その他の stdio MCP クライアント

次の汎用サーバー定義を使用してください。

{
  "command": "uvx",
  "args": ["mac-messages-mcp"]
}

GUI クライアントで uvx が見つからないと表示された場合は、Terminal で which uvx を実行し、返された絶対パスで "uvx" を置き換えてください。Homebrew では、Apple シリコンの Mac に /opt/homebrew/bin/uvx、Intel Mac に /usr/local/bin/uvx としてインストールされることがよくあります。

4. 接続を確認する

クライアントに tool_check_db_access、次に tool_check_addressbook を呼び出すよう依頼してください。両方が成功したら、次のようなプロンプトを試してください。

Show me my messages from the last two hours.
Find messages from Carter about dinner in the last 30 days.
Find PDFs sent to me this month, but do not open any yet.
Find Jordan in my contacts and draft a message saying I am running 10 minutes
late. Do not send it until I confirm.

初回の uvx の起動では、Python の依存関係をダウンロードしてキャッシュするため、時間がかかる場合があります。

5. 任意:電話番号の地域を設定する

国内形式で記述された電話番号(06 39 98 00 01、(415) 555-1234)は、Messages データベースと照合する前に E.164 形式に変換する必要があり、その変換には対象の国を把握する必要があります。サーバーはこの情報に Mac 自体の地域設定を使用するため、正しく設定された Mac では何もする必要はありません。

電話番号が Mac の設定とは異なる地域のものの場合は、MAC_MESSAGES_REGION にISO 3166-1 alpha-2コードを設定してください。たとえば、en_US に設定された Mac でフランスの SIM を使用する場合です。

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"],
      "env": { "MAC_MESSAGES_REGION": "FR" }
    }
  }
}

Claude Code の場合:

claude mcp add --transport stdio --scope user \
  --env MAC_MESSAGES_REGION=FR \
  mac-messages -- uvx mac-messages-mcp

地域は起動時に一度だけ解決されるため、変更後はサーバーを再起動してください。解決の優先順位は、MAC_MESSAGES_REGION、macOS の AppleLocale 環境設定、LC_ALL/LC_CTYPE/LANG、そして US です。すでに E.164(+33639980001)形式で記述されている電話番号は再解釈されないため、これらの設定は不要です。

利用可能なツール

ツール用途副作用
tool_get_recent_messages連絡先、グループチャット ID、日付範囲、または未読状態で絞り込んで最近のメッセージを読み込みます。limit/offset でページ分割できます読み取り専用
tool_fuzzy_search_messages連絡先またはチャットを対象に、あいまいなテキスト一致でメッセージ本文を検索します。デフォルトでは過去 30 日間が対象です。hours=0 も指定できます読み取り専用
tool_list_conversations種類、メッセージ数、未読数、最終アクティビティとともに、すべての会話を一覧表示します読み取り専用
tool_wait_for_new_messagesROWID カーソルより新しいメッセージが届くか、タイムアウトになるまで待機します読み取り専用
tool_find_contact連絡先から名前をあいまい検索し、電話番号を返します読み取り専用
tool_get_chats名前付きグループチャットとその識別子を一覧表示します読み取り専用
tool_search_attachments日付、連絡先、MIME タイプ、件数上限で添付ファイルのメタデータを検索します読み取り専用
tool_search_attachment_contents日付、連絡先、MIME タイプで添付ファイルのテキストや PDF の内容を検索します読み取り専用
tool_get_attachmentID を指定して添付ファイルを取得します。対応している場合はインラインで、そうでない場合はローカルパスで返します読み取り専用
tool_check_imessage_availability電話番号またはメールアドレスについて、iMessage が利用可能かどうかを確認します読み取り専用
tool_check_db_access~/Library/Messages/chat.db へのアクセスを診断します読み取り専用
tool_check_contacts連絡先の件数と少数のサンプルを返します読み取り専用
tool_check_addressbookContacts/AddressBook データベースへのアクセスを診断します読み取り専用
tool_send_messageMessages.app から個別またはグループメッセージを送信します。ファイルの添付や、エリシテーションによる承認も指定できます実際のメッセージを送信します
tool_create_contact電話番号を指定して Contacts.app に連絡先を 1 件作成します連絡先を変更します
tool_schedule_messageこのサーバープロセスの実行中に、後で配信するメッセージをキューに登録します後で実際のメッセージを送信します
tool_list_scheduled_messagesプロセス内の予約メッセージキューとその状態を一覧表示します読み取り専用
tool_cancel_scheduled_message保留中の予約メッセージを 1 件キャンセルします読み取り専用
3 つの MCP プロンプトがサーバーに同梱されています。triage_unread_messages、
summarize_recent_messages、draft_reply です。これらはエージェントにどの読み取りツールを呼び出すかを指示する出発点であり、メッセージを送信することはありません。

サーバーは 2 つの MCP リソースも公開しています。

  • messages://recent/{hours}
  • messages://contact/{contact}/{hours}
メッセージのメタデータ、ページング、カーソル

出力を古いデータベースや一部のデータしかないデータベースでも変わらないように保つため、メッセージ行にデータが含まれている場合、読み取り時に簡潔なタグが追加されます。

[2026-10-01 09:14:02] Alice [iMessage] [unread]: running late, sorry
[2026-10-01 09:15:40] You [iMessage] [not delivered]: no worries
[2026-10-01 09:15:55] Alice [iMessage] [tapback: liked]: (reaction)
[2026-10-01 09:16:10] Bob [SMS] [reply]: got it

tool_get_recent_messages は、ページがいっぱいになると、次に使用する offset を示す注記を最後に付けます。since_rowid を渡すと、前方カーソル読み取り(古い順)に切り替わり、hours の期間指定は無視されます。これは tool_wait_for_new_messages がポーリングに使用する方式です。

意図的に対応していないこと

Messages.app の自動化では以下に対応していないため、サーバーはできるふりをするのではなく、要求を拒否します。

  • タップバック、メッセージエフェクト、件名の送信(送信できるのはテキストとファイル添付のみです)
  • グループチャットの作成、参加者の追加または削除、グループチャットへのファイル添付
  • メッセージの編集、送信取り消し、削除、既読への変更、下書きの保存
  • 既存の連絡先カードの編集または統合(tool_create_contact は新規カードを作成します)
  • 予約送信はサーバープロセスが稼働し続けることを前提としています。何も永続化されないため、クライアントが先に切断すると予約メッセージは失われます

エージェントスキル

このリポジトリには、各ツールをいつ、どのように呼び出すかをエージェントに指示するエージェントスキルが同梱されています。アクセスの確認、会話の一覧表示、宛先またはグループチャットの特定、メッセージテキストや添付ファイルの内容の検索、添付ファイルのページング、送信の確認、後で送信する予約、メッセージ由来の出力を信頼できないデータとして扱う方法を説明します。このリポジトリで作業すると、Claude Code が自動的に検出します。

別のプロジェクトで使用するには、スキルディレクトリをそのプロジェクトの .claude/skills/ にコピーするか、どこからでも利用できるように ~/.claude/skills/ にコピーします。

mkdir -p ~/.claude/skills
cp -R .claude/skills/mac-messages ~/.claude/skills/

連絡先、チャット、添付ファイルの操作

宛先

ダイレクトメッセージでは、E.164 形式の電話番号が最も確実です。

+14155551234

国内形式で記述した番号も使用できます。Mac で設定されている地域に基づいて E.164 形式に変換されるため、米国の Mac では (415) 555-1234 が +14155551234 に、フランスの Mac では 06 39 98 00 01 が +33639980001 になります。番号が Mac に設定されている地域とは異なる地域のものなら、MAC_MESSAGES_REGION に ISO 3166-1 alpha-2 コードを設定してください(MAC_MESSAGES_REGION=GB)。E.164 形式の番号は再解釈されません。

メールアドレス、連絡先名、曖昧な連絡先検索の後に返される contact:N の選択肢も使用できます。

グループの会話では、tool_get_chats を呼び出し、そのチャット ID を tool_send_message に渡して、group_chat=true を設定します。その会話を読み取るには、同じ ID を tool_get_recent_messages の chat_id として使用します。

添付ファイル

添付ファイルへのアクセスは、意図的に次の 3 段階に分かれています。

  1. メッセージの読み取りと検索では、[attachments: #42 image/jpeg (invitation.jpg)] のような簡潔なマーカーが追加されます。
  2. tool_search_attachments は、ファイルの内容を読み込まずにメタデータを検索します。
  3. tool_get_attachment は、選択した添付ファイルを 1 つ取得します。

5 MB 以下の画像は、デフォルトでインライン表示されます。HEIC 画像は PNG に変換されます。これより大きな画像、PDF、動画、音声はローカルファイルシステムのパスとして返されるため、MCP クライアントが開くかどうかを判断できます。ステッカー、リンクプレビューのペイロード、.pluginPayloadAttachment コンテナは除外されます。

アーキテクチャ

Mac Messages MCP は、各モジュールが 1 つの役割を担う小規模な Python パッケージです。

mac_messages_mcp/
  server.py       FastMCP server: tools, prompts, resources, stdio transport
  cli.py          mac-messages-cli terminal interface
  messages.py     chat.db reads and AppleScript sends for Messages.app
  content.py      Best-effort text/PDF attachment content search
  phone.py        E.164 normalization against the Mac's configured region
  scheduler.py    In-process scheduled-send queue
  untrusted.py    Structural neutralization of Messages/Contacts-derived text
scripts/
  build_mcpb.py   Builds the Claude Desktop .mcpb extension
  bump_version.py Keeps version metadata in sync across release files
tests/            Pytest suite over temporary databases and mocked AppleScript
main.py           Stdio entry point for MCP clients
manifest.json     MCPB manifest for the Claude Desktop extension

読み取りは chat.db と AddressBook データベースに直接アクセスし、送信は AppleScript を介して Messages.app に送られます。モデル向けのペイロードは、クライアントに届く前に untrusted.py を通ります。

プライバシーとセキュリティ

  • Messages と Contacts の SQLite 接続では、読み取り専用モードと SQLite の query_only を使用します。
  • サーバーはメッセージをアップロード、複製、インデックス化したり、独自のメッセージ アーカイブを保持したりしません。
  • 結果は、クライアントが開始したローカルの MCP stdio 接続に書き込まれます。
  • Messages/Contacts 由来のツールおよびリソースの出力は、構造的に無害化されます(埋め込まれた改行や ASCII 制御文字によって追加のトランスクリプト行を作成できず、不可視文字、書式文字、双方向制御文字はエスケープとして表示されます)。また、明示的な <untrusted-mcp-output> ブロック内に返されます。 これはインジェクションを防ぐ保証ではありません。サードパーティーの iMessage/SMS コンテンツが、引き続きプロンプトインジェクションを試みる可能性があります。サーバーはそのコンテンツを構造的に無害化してラベル付けしますが、クライアントはそれを認可、確認、またはツールへの指示として扱ってはなりません。
  • 添付ファイルのバイトデータは明示的に取得した場合にのみ返され、インライン画像にはサイズ制限が適用されます。ファイル名、MIME、パス、その他のメタデータテキストも同じ境界で無害化されます。画像データはそのまま保持されます。
  • 送信は tool_send_message 内に隔離され、AppleScript の入力をエスケープし、実行時間に上限を設けています。このサーバーは人間による確認を行いません。送信を制御するのは MCP クライアントの役割です。
  • フルディスクアクセスは Messages へのアクセスより広範な権限です。信頼できる MCP クライアントのみに許可し、送信を承認する前に宛先を確認してください。

脆弱性を非公開で報告する場合は、SECURITY.md をご覧ください。

トラブルシューティング

uvx または spawn uvx ENOENT

GUI アプリからシェルの Homebrew パスを参照できません。次を実行してください。

which uvx

その絶対パスを MCP の command として使用し、クライアントを再起動してください。

Operation not permitted、unable to open database file、またはメッセージが表示されない

Messages.app だけでなく、サーバーを起動するアプリにフルディスクアクセスを許可してください。その後、起動アプリを完全に終了して再度開き、tool_check_db_access をもう一度呼び出してください。

Claude Code または Codex CLI の場合、通常はターミナルが起動アプリです。デスクトップまたは IDE との連携では、通常、Claude Desktop、Cursor、VS Code、または ChatGPT デスクトップアプリ自体が起動アプリです。

連絡先が空、または連絡先の検索に失敗する

macOS から求められた場合は、起動アプリによる連絡先へのアクセスを許可してください。フルディスクアクセスを確認し、アプリを再起動してから、tool_check_addressbook、続いて tool_check_contacts を呼び出してください。

連絡先は表示されるものの、電話番号の国番号が間違っている場合、サーバーが国番号形式に変換する際に誤った地域を使用しています。MAC_MESSAGES_REGION に正しい ISO 3166-1 alpha-2 コードを設定し、サーバーを再起動してください。

読み取りはできるが送信に失敗する
  1. Messages.app を開き、アカウントと宛先が機能することを確認するため、手動でメッセージを送信してください。
  2. システム設定 → プライバシーとセキュリティ → オートメーションを確認し、起動アプリによる Messages の操作を許可してください。
  3. 直接の宛先には +14155551234 のような E.164 形式の電話番号を使用してください。
  4. tool_check_imessage_availability を使って、可能性の高い経路を確認してください。
添付ファイルは一覧に表示されるが、開けない

macOS がファイルをオフロードした後も、Messages にデータベースのメタデータが残っている場合があります。Messages.app で会話を開いて添付ファイルをダウンロードしてから、tool_get_attachment を再試行してください。

Terminal で実行するとサーバーが停止したように見える

MCP stdio サーバーでは正常な動作です。クライアントからのプロトコル入力を待機しています。クライアントの MCP ステータス画面を使用するか、MCP Inspector を起動してください。

yarn dlx @modelcontextprotocol/inspector uvx mac-messages-mcp

スタンドアロンツールとしてインストールする

MCP クライアントは uvx でパッケージを直接起動できます。恒久的なインストールは任意です。

uv tool install mac-messages-mcp
mac-messages-mcp

アップグレードまたは削除するには、次を実行してください。

uv tool upgrade mac-messages-mcp
uv tool uninstall mac-messages-mcp

Python API

MCP サーバーが主要なインターフェースですが、このパッケージでは読み取り/送信の中核関数もエクスポートしています。

from mac_messages_mcp import get_recent_messages, send_message

recent = get_recent_messages(hours=48)
print(recent)

result = send_message(
    recipient="+14155551234",
    message="Hello from Mac Messages MCP!",
)
print(result)

これらの呼び出しでは同じ macOS の権限が使用され、実際のメッセージを送信できます。

コマンドラインインターフェース

このパッケージをインストールすると、mac-messages-cli コマンドも使えるようになります。MCP クライアントがなくても、ターミナルからメッセージの閲覧、検索、送信ができます。このコマンドはサーバーと同じローカルデータベースを使用し、同じ macOS のアクセス許可が必要です。ターミナルにフルディスクアクセスを許可すると、どちらも利用できます。

uv tool install mac-messages-mcp
mac-messages-cli --help
コマンド目的
recent最近のメッセージを表示します。連絡先またはグループチャット ID で絞り込むこともできます。
search TERM指定した期間内のメッセージ本文をあいまい検索します。
contact NAME連絡先で名前をあいまい検索し、送信に使える電話番号を表示します。
contacts連絡先数と AddressBook の項目のサンプルを表示します。
chats名前付きグループチャットとその識別子を表示します。
attachments日付範囲、連絡先、MIME タイプで絞り込んだ添付ファイルのメタデータを表示します。
attachment ID1 件の添付ファイルのメタデータとローカルパスを表示します。--save も指定できます。
sendMessages.app からメッセージを 1 件送信します。
checkMessages/AddressBook へのアクセスと iMessage の到達可能性を診断します。
# Last 48 hours, or one contact, or one group chat
mac-messages-cli recent -n 48
mac-messages-cli recent --contact "Jordan"
mac-messages-cli recent --chat chat721054478304420871

# Fuzzy search: last 30 days by default, or all history with -n 0
mac-messages-cli search "dinner" -t 0.7
mac-messages-cli search "dinner" -n 0

# Contacts and group chats
mac-messages-cli contact "Jordan"
mac-messages-cli chats

# Attachments: search metadata, then fetch or save one file
mac-messages-cli attachments --since 2026-09-01 --mime image/ --limit 20
mac-messages-cli attachment 42 --save ~/Desktop/invitation.jpg

# Permissions and iMessage reachability
mac-messages-cli check --recipient +14155551234

# Sending prompts for confirmation unless --yes is passed
mac-messages-cli send +14155551234 "Running 10 minutes late."

mac-messages-cli send は、送信前に y/N の確認を求めます。標準入力がターミナルでない場合、--yes を指定しないと送信を拒否するため、無人スクリプトから誤ってメッセージが送信されることはありません。検索に失敗した場合、コマンドは 0 以外の終了コードを返すため、スクリプトで安全に条件分岐できます。

開発

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

uv sync --frozen --extra dev
uv run pytest
uv run black --check .
uv run isort --check-only .
uv build

テストでは AppleScript をモックし、一時的なデータベースのフィクスチャを使用します。コントリビューターの実際の Messages や Contacts のデータを読み取ることはありません。コントリビューションのチェックリストについてはCONTRIBUTING.mdを、リリースについてはVERSIONING.mdを参照してください。

Claude Desktop 拡張機能をビルドする

このリポジトリには MCPB の manifest.json と、アーキテクチャに合わせた uv バイナリを同梱できるビルドスクリプトが含まれています。

yarn global add @anthropic-ai/mcpb
uv run python scripts/build_mcpb.py

Intel 向けにビルドするには、次のようにします。

uv run python scripts/build_mcpb.py --arch x86_64

生成された .mcpb は、Claude Desktop → Settings → Extensions → Advanced settings → Install Extension… からインストールしてください。同梱された拡張機能でも、初回起動時に Python とパッケージの依存関係をダウンロードするため、ネットワークアクセスが必要です。

システムの uv を使ってパッケージ化するには --no-bundle を指定してください。すべてのオプションを確認するには、uv run python scripts/build_mcpb.py --help を実行してください。

Docker

付属の Dockerfile は、パッケージとカタログの検証に使用します。Linux コンテナから macOS の TCC アクセス許可を利用したり、Messages.app を自動操作したりすることはできないため、ホストの Mac でメッセージを読み取ったり送信したりする方法として Docker はサポートされていません。

ドキュメント

ドキュメント目的
エージェントスキルエージェントが各ツールを呼び出すタイミングと方法
コントリビューション開発ワークフロー、チェック、プルリクエストの基準
セキュリティ脆弱性の非公開報告と信頼モデル
バージョン管理リリースとバージョンメタデータのプロセス
変更履歴リリースごとのユーザー向け変更

コントリビューション

Issue や、焦点を絞ったプルリクエストを歓迎します。バグ報告やフィクスチャに、実際のメッセージ本文、連絡先、電話番号、データベースファイル、添付ファイルを含めないでください。

ライセンス

MIT © Carter Lasalle

コメント

MCP は初めてですか?

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

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