IMCP

iMCP は、デジタルライフと AI をつなぐ macOS アプリです。 Claude Desktop、 ChatGPT デスクトップアプリ、 llama.cpp で提供されるローカルモデル、 および Model Context Protocol (MCP) に対応した 増え続けるクライアントの一覧で利用できます。

機能

	カレンダー	カレンダーの予定を表示、管理できます。繰り返し、アラーム、空き状況などの設定をカスタマイズして、新しい予定を作成することもできます。
	連絡先	自分の連絡先情報にアクセスし、名前、電話番号、またはメールアドレスで連絡先を検索できます。
	ホーム	ホーム、部屋、アクセサリ、シーン、自動化を検索し、アクセサリの情報を読み取って操作したり、部屋やゾーンを整理したりできます。ご自身のApple Developerアカウントを使ってビルドするヘルパーアプリが必要です。
	位置情報	現在地データにアクセスし、住所と地理座標を相互に変換できます。
	メール	メールボックスの一覧表示、送信者、件名、メールボックス、日付、既読状況によるメッセージの検索、Macに保存されているメッセージの閲覧、デフォルトのメールアプリでの新規下書きの作成ができます。メールの閲覧には、メールフォルダへのアクセスが必要です。
	マップ	場所の検索、経路案内、施設の検索、所要時間の推定、静的な地図画像の生成など、位置情報サービスを提供します。
	メッセージ	日付範囲をカスタマイズして、特定の相手とのメッセージ履歴にアクセスできます。
	ミュージック	ミュージックアプリで再生中の内容を確認し、再生を操作したり、Apple Musicカタログを検索したりできます。再生ツールにはミュージックのオートメーション権限が必要です。カタログの検索にはApple Musicへのアクセスが必要です。
	メモ	テキスト、フォルダ、または日付でメモを検索し、チェックリスト、表、リンクを含むMarkdown形式で読み取れます。
	電話	iPhoneから同期された通話履歴を表示し、相手、日付、または通話の種類で通話を絞り込んだり、システムの確認を経て通話を開始したりできます。
	リマインダー	リマインダーリストをまたいで、期限、繰り返し、優先順位、通知をカスタマイズしながら、リマインダーの表示、作成、編集、削除ができます。リスト自体の管理も可能です。
	ショートカット	Mac上のショートカットを一覧表示して実行できます。必要に応じてテキスト入力も渡せます。
	ボイスメモ	タイトル、フォルダ、日付で絞り込んで、文字起こしと音声を含むボイスメモの録音を取得したり、「最近削除した項目」を確認したりできます。ボイスメモフォルダへのアクセスが必要です。
	ボイスメール	iPhoneから同期されたボイスメールを、文字起こしと音声とともに取得できます。送信者、日付、メッセージの種類、またはメールボックス（受信、ブロック、削除）で絞り込めます。
	天気	任意の場所の気温、風速、天候など、現在の気象状況にアクセスできます。

iMCP を使うには、2 つのアプリが必要です。 有効にしたサービスへのアクセスを提供する iMCP と、 MCP サーバーに接続できる AI アプリです。 まず iMCP をインストールし、サービスを有効にしてください。 その後、使用する AI アプリの手順に従ってください。

• Claude Desktop
• ChatGPT デスクトップアプリ
• Claude Code、llama.cpp、その他のクライアント

アプリをダウンロードして開く

まず、iMCP アプリをダウンロードしてください （macOS 15.3 以降が必要です）。

または、Homebrew がインストールされている場合は、 次のコマンドを実行できます。

brew install --cask mattt/tap/iMCP

アプリを開くと、 メニューバーに アイコンが表示されます。

このアイコンをクリックして、iMCP メニューを開きます。 上部にある青色の「Enable MCP Server」スイッチは、 MCP サーバーが実行中で、AI アプリに接続する準備ができていることを示します。 AI アプリが iMCP を使うには、iMCP を開いておく必要があります。

スイッチの下には、利用可能なサービスが一覧表示されます。 iMCP を初めて開いたときは Maps が有効になっており、 それ以外のサービスは無効で、グレーで表示されます。 iMCP には、システムサウンドを再生するツールも含まれています。 このツールは、すべてのサービスが無効でも常に利用できるため、 権限を許可せずに接続をテストできます。

サービスを有効にする

サービスを有効にするには、そのアイコンをクリックします。 macOS から権限を求められます。 たとえば Calendar を有効にすると、 「“iMCP”があなたのカレンダーへのフルアクセスを求めています」というダイアログが表示されます。 「フルアクセスを許可」をクリックして続行します。

重要

iMCP は、あなたのデータを収集も保存もしません。 Claude や ChatGPT などの AI アプリは、ツール呼び出しの一環として、 データをデバイス外に送信します。 AI アプリに使わせたいサービスだけを有効にしてください。 データを Mac 上に保持するには、 llama.cpp でローカルモデルを使用してください。

サービスが有効になると、 アイコンの色がグレーからサービスの色に変わります。 Calendar は赤、Messages は緑、Location は青などです。

使用するサービスごとに、これらの手順を繰り返してください。 macOS は権限を個別に求めるため、 iMCP がアクセスできるのは許可したデータだけです。 サービスを無効にするには、もう一度そのアイコンをクリックします。 サービス内の個別のツールを無効にするには、 >「設定」をクリックし、サイドバーでサービスをクリックします。

接続を承認する

AI アプリが初めて接続すると、 iMCP に「クライアント接続要求」ダイアログが表示されます。 このダイアログには、アプリが報告する名前と、 アプリが使用できるサービスが表示されます。 接続するには「許可」をクリックします。 次回からこのダイアログを省略するには、「このクライアントを常に信頼する」を選択してください。 その後、アプリが接続するたびに iMCP から通知が表示されます。 信頼済みのクライアントは、 >「設定」>「クライアント」から削除できます。

メールストアへのアクセスにはEnvelopeを使用します。 Envelopeはローカルのインデックスとメッセージファイルを読み込み、 内部のMIMEリーダーで読み取り可能なコンテンツを選択します。 iMCPはフォルダーへのアクセス、ツールの引数、JSON出力、メールの作成を管理します。

メールの読み取りには~/Library/Mailへのアクセスが必要です。 フォルダーにアクセスできない場合でも、mail_composeを使って デフォルトのメールアプリで作成ウィンドウを開けます。 メッセージの保存や送信は行いません。

メールの読み取りには読み取り専用のSQLite接続を使用し、WALジャーナルモードが必要です。 iMCPはインデックスのジャーナルモードを変更せず、チェックポイントも実行しません。 Mailデータベースへの接続は一度に1つまでです。 同時に読み取りが行われる場合は順番を待ち、 SQLiteがロックの競合を報告すると読み取りはエラーを返します。 各SQL文の実行時間は100 msまでで、 1回の読み取りに含まれるすべての文の合計時間は1 sまでです。 各文はタスクのキャンセルを確認します。 この期限は協調的なものであり、SQLiteが処理の完了を待っている間、 ファイルシステム操作を中断することはできません。 時間のかかる検索は、結果を返さずに失敗する場合があります。 サービスの状態確認ではSQLite接続を開きません。 また、メッセージの読み取りでは、メールボックスファイルをスキャンする前にデータベースを閉じます。 これらの制限によって干渉は軽減されますが、読み取り中にWALチェックポイントが遅れる場合があります。

mail_messages_searchのmailboxフィルターには、 mail_mailboxes_listから取得した@id文字列を使用します。 たとえば、{"mailbox": "V10:12"}のように指定します。 識別子にはMailストアが含まれるため、 Mailストアのアップグレード前の識別子を使うとエラーになります。 urlフィールドはストレージを示すもので、検索用の識別子ではありません。 メールボックスには、利用可能な場合、アカウント識別子が含まれます。 アカウントのemailフィールドはMailのローカルアカウントマップから取得されます。 このマップがない場合、またはメールアドレスが含まれていない場合はnullになります。

検索結果には、フィルターやページネーションの適用前に、 選択したメールボックスのlocalIndex.indexedMessageCountが含まれます。 メールボックスを選択していない場合は、すべてのメールボックスの件数が含まれます。 この件数にはラベルへの所属も含まれますが、同じメッセージが重複して数えられることはありません。 同期状態はunknownとして報告されます。 件数が0の場合、メールボックスが空であるか、ローカルのインデックスが存在しない可能性があります。 Mailがそのアカウントを一度でもインデックス化したかどうかは判断できません。 アカウントの同期状況を確認するにはMailを開いてください。

検索結果は新しいメッセージから順に表示されます。 一致するメッセージがほかにもある場合、結果にはnextCursorの値が含まれます。 同じフィルターを指定して、この値をcursorとして渡すと次のページを取得できます。 カーソルはページ内の最後のメッセージを示すため、 リクエストの間にメールが届いても、後続のページの位置はずれません。

検索対象は送信者と件名のメタデータのみです。 mail_messages_readでは、返されたメッセージのローカルコンテンツを読み取れます。 添付ファイルは一覧表示されますが、内容は読み取れません。 Mailがメッセージの添付ファイルやインライン画像を別ファイルとして保存している場合、 メッセージファイルにはテキストが保持され、各添付ファイルの isStoredSeparatelyはtrueに設定されます。 本文の検索には対応しておらず、これらのツールはメッセージをダウンロードしません。

Claude Desktopに接続する

Claude Desktopがインストールされていない場合は、 こちらからダウンロードできます。

Claude Desktopを開き、Claude > 「Settings」（⌘,）を選択します。 サイドバーの「Developer」をクリックし、 続けて「Edit Config」をクリックします。 これにより、次の場所に設定ファイルが作成されます。 ~/Library/Application Support/Claude/claude_desktop_config.json

iMCPをClaude Desktopに接続するには、 > 「Configure Claude Desktop」をクリックし、 続けて「Set Up」をクリックします。

iMCPは設定ファイル内のエントリを追加または更新し、 Claude Desktopがアプリ内のimcp-server実行ファイルを起動するようにします。 iMCPはファイル内のほかのMCPサーバーを保持します。

Claude Desktopを手動で設定する

\> 「Copy server command to clipboard」をクリックします。 次に、エディターで`claude_desktop_config.json`を開き、 以下を入力します。

{
  "mcpServers": {
    "iMCP": {
      "command": "{paste iMCP server command}"
    }
  }
}

Claude Desktop アプリを終了して、再度開きます。 iMCP が接続の承認を求めます。

接続を承認すると、 チャットボックスの右下に、 利用可能なツールの数を示す 🔨 アイコンが表示されます。 クリックすると、Claude が使える iMCP ツールを確認できます。

これで、次のように、 個人データへのアクセスが必要な質問を Claude にできます。

"今いる場所の天気はどうですか？"

Claude は iMCP ツールを使ってこの情報を取得するため、 会話で自分から共有する必要はありません。

ChatGPT デスクトップアプリに接続する

ChatGPT デスクトップアプリがインストールされていない場合は、 こちらからダウンロードできます。

メモ

以下の手順は macOS 版 ChatGPT 26.930 のラベルを使用しています。 また、最初から最後までの動作確認はまだ行われていません。 OpenAI は Codex モード向けの MCP サーバーについて説明しているため、 Codex の会話で iMCP を使用してください。

1. \> 「Copy server command to clipboard」をクリックします。
2. ChatGPT で「Settings」（⌘,）を開き、 サイドバーの「MCP servers」をクリックします。
3. 「Add server」をクリックします。 「Name」に iMCP を入力し、「Type」で「STDIO」を選択して、 コピーしたコマンドを「Command to launch」に貼り付けます。 ほかのフィールドは空のままにします。
4. 「Save」をクリックし、続けて「Restart」をクリックします。
5. iMCP で接続を承認します。 ChatGPT は自分自身を codex-mcp-client として識別する場合があります。

接続をテストするには、 新しい Codex の会話を開始して、次のメッセージを送信します。

"iMCP を使ってシステムサウンドを再生してください。"

Mac から短いサウンドが再生されます。 Mac がミュートされている場合は、会話内でツール呼び出しを開いてください。 結果が true であれば、iMCP がリクエストを受信したことを意味します。

ほとんどの MCP クライアントでは、STDIO トランスポートを使用するローカルサーバーとして iMCP を起動できます。 >「サーバーコマンドをクリップボードにコピー」をクリックし、 コピーしたコマンドを、クライアントで新しい STDIO サーバーのコマンドとして入力してください。 コピーされるコマンドは、お使いの iMCP 内にある imcp-server 実行ファイルへのフルパスです。

以下のコマンドは、iMCP が Applications フォルダーにあることを前提としています。 iMCP を別の場所にインストールした場合は、 /Applications/iMCP.app/Contents/MacOS/imcp-server をコピーしたコマンドに置き換えてください。

Claude Code

すべてのプロジェクトに iMCP を追加するには、次のコマンドを実行します。

claude mcp add --scope user iMCP -- /Applications/iMCP.app/Contents/MacOS/imcp-server

claude mcp add-from-claude-desktop

llama.cpp

llama.cpp を使って Mac 上で実行するオープンモデルで iMCP を利用できるため、 会話やツールの結果を Mac 上にとどめられます。 llama-server（または llama serve）は、設定ファイルに記載された MCP サーバーを起動し、 そのツールをウェブ UI 内のモデルに提供します。 これには llama.cpp 0.1.0 以降が必要です。

次の内容で ~/.config/llama/mcp.json ファイルを作成します。

{
  "mcpServers": {
    "imcp": {
      "command": "/Applications/iMCP.app/Contents/MacOS/imcp-server"
    }
  }
}

次に、--mcp-servers-config オプションと、ツール呼び出しに対応したモデルを指定してサーバーを起動します。

llama serve --mcp-servers-config ~/.config/llama/mcp.json \
            -hf ggml-org/Qwen3-4B-GGUF

http://localhost:9931 でウェブ UI を開きます （llama.cpp のバージョンが 0.7.0 より前の場合は、ポート 8080 を使用します）。 iMCP のツールは、imcp_weather_current のように imcp_ プレフィックス付きで表示されます。 常にそのツールを許可する設定にしない限り、ウェブ UI ではツール呼び出しの実行前に確認が求められます。

defaults write app.llama.Llama extraServerArgs -string "--mcp-servers-config $HOME/.config/llama/mcp.json"

重要

サーバーの起動時、 iMCP がツール一覧を返すまで 10 秒間待機します。 その時間内に「llama.cpp」からの接続を承認しない場合、 サーバーを再起動するまで iMCP のツールは表示されません。

技術的な詳細

アプリと CLI

iMCP は、コマンドライン実行ファイル imcp-server をバンドルした macOS アプリです。

• iMCP.app は、サービスを設定するための UI と、最も重要な機能として、 macOS のシステム権限を操作する手段を提供します。 これにより、連絡先、カレンダーなどの情報にアクセスできます。
• imcp-server は、標準入出力を使って通信する MCP サーバーを提供します （stdio トランスポート）。

アプリと CLI は、Bonjour を使った自動検出により、ローカルネットワーク上で相互に通信します。 どちらもタイプが「_mcp._tcp」、ドメインが「local」のサービスをアドバタイズします。 MCP クライアントからのリクエストは CLI が stdin から読み取ってアプリに中継し、 アプリからの応答は CLI が受信して stdout に書き込みます。 実装の詳細については、StdioProxy を参照してください。

このプロジェクトでは、Model Context Protocol のサーバーとクライアント向けの 公式 Swift SDKとなったものを作成しました。 アプリはこのパッケージを使って、MCP クライアントから中継されたリクエストを処理します。

iMessage データベースへのアクセス

Apple は、メッセージにアクセスするための公開 API を提供していません。 ただし、macOS のメッセージアプリは、~/Library/Messages/chat.db にある SQLite データベースにデータを保存しています。

iMCP はアプリサンドボックス内で動作するため、ユーザーデータやシステムリソースへのアクセスが制限されています。 メッセージサービスを有効にすると、標準のファイル選択ダイアログで ~/Library/Messages フォルダを選択するよう求められます。 選択すると、macOS はそのフォルダへのアクセスをアプリのサンドボックスに許可します。 NSOpenPanel はこのように便利な仕組みです。 フォルダ全体が必要なのは、chat.db が WAL モードのデータベースであり、メッセージアプリが新しいメッセージをまず隣接する chat.db-wal に書き込み、数 MB ごとにチェックポイントを実行したときにのみ、そのログを chat.db に統合するためです。チェックポイントの実行は数時間後になることもよくあります。 chat.db だけにアクセスを許可した場合（以前のバージョンで求めていた許可方法）、ログを読み取れないため、チェックポイントが実行されるまで最新のメッセージが表示されませんでした。 以前のバージョンで chat.db へのアクセスを許可した場合、メッセージアプリは最後のチェックポイント時点の状態で動作します。iMCP メニューでメッセージをいったんオフにしてからオンにし、フォルダへのアクセスを許可してください。

添付ファイルは別に扱われます。 サンドボックスは親フォルダへのアクセスを許可しても ~/Library/Messages/Attachments を隔離するため、メッセージの添付ファイルを読み取るには（messages_attachment_read）、同じファイル選択ダイアログでこのサブフォルダへのアクセスを求められます。これは個別の読み取り専用の許可です。 許可するかどうかは任意です。 許可しない場合、messages_attachment_read ではファイルを読み取れませんが、ほかの機能は引き続き動作します。 添付ファイルがサポートされる前にメッセージフォルダへのアクセスを許可した場合は、iMCP メニューでメッセージをいったんオフにしてからオンにすると、このフォルダへのアクセスを求められます。

ただし、iMessage データベースを開くことは、課題の半分にすぎません。 ここ数年、Apple はメッセージをプレーンテキストで保存する方式から離れ、独自の typedstream 形式に移行しています。

このプロジェクトでは、iMessage データベースを読み取るための Swift パッケージ、Madrid を作成しました。 これには、Christopher Sardegna の imessage-exporter プロジェクトと、typedstream のリバースエンジニアリングに関するブログ記事を基にした、Apple の typedstream 形式をデコードする Swift 実装が含まれています。

通話履歴データベースへのアクセス

iPhone から同期された通話履歴は、~/Library/Application Support/CallHistoryDB/CallHistory.storedata にある SQLite データベースに保存されています。 最近の通話はストアファイルの隣にある先行書き込みログに保存されるため、電話サービスではファイルだけでなく CallHistoryDB フォルダを開くよう求められます。

ビジュアルボイスメールデータベースへのアクセス

電話アプリによって iPhone から同期されたボイスメール（macOS 26 以降）は、~/Library/Group Containers/group.com.apple.FaceTime/com.apple.facetimemessagestored/Data Store/FaceTimeMessageStore-local.sqlitedb にある SQLite データベースに保存されています。 このストアは先行書き込みログ方式のデータベースで、メッセージの音声データは隣接する Assets ツリーに保存されるため、ボイスメールサービスではファイルだけでなく Data Store フォルダを開くよう求められます。

ボイスメモライブラリへのアクセス

ボイスメモは、~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/CloudRecordings.db にある SQLite データベースにライブラリを保存しています。 音声ファイルはデータベースの隣に保存されるため、ボイスメモサービスではファイルだけでなく Recordings フォルダを開くよう求められます。 ボイスメモは各文字起こしを録音の音声ファイルに保存するため、Mac に音声データがある録音にのみ文字起こしが含まれます。

このプロジェクトでは、ボイスメモライブラリを読み取るための Swift パッケージ、TSRP を作成しました。 文字起こしは .m4a ファイルと .qta ファイルの両方から読み取ります。それぞれ保存場所が異なります。

Notes データベースへのアクセス

Apple は、メモにアクセスするための公開 API も提供していません。 メモアプリは、メモを SQLite データベース ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite に保存します。 最近の編集内容は先行書き込みログに記録されるため、 メモサービスではファイル単体ではなく、 group.com.apple.notes フォルダを開くよう求められます。 iMCP はデータベースを読み取るだけで、メモを変更することはありません。

各メモの内容は、gzip 圧縮されたプロトコルバッファとして保存されています。 テキストの後に、各部分の書式を示す範囲が続きます。 テーブルは個別に保存され、各交差点の行、列、セルを列挙する CRDT の状態として記録されます。 パスワードでロックされたメモは暗号化されているため、 iMCP はタイトルで見つけられますが、内容を読み取ることはできません。

このプロジェクトでは、TopoText を作成しました。 これはメモデータベースを読み取るための Swift パッケージで、 メモのテキスト形式に対する Apple の内部名称にちなんで名付けられています。 Jon Baumann の apple_cloud_notes_parser と Steve Dunham の notesutils によるリバースエンジニアリングを基にしています。 メモサービスは TopoText でメモを読み取り、Markdown として返します。

ツールの結果に対する JSON-LD

iMCP が提供するツールは、 JSON-LD ドキュメントとして結果を返します。 たとえば、 fetchContacts ツールは Contacts フレームワーク を使用します。 このフレームワークでは、人や組織を CNContact 型で表します。 この型のオブジェクトは、JSON-LD で次のようにエンコードされます。

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Mattt",
  "url": "https://mat.tt"
}

contacts_search のようにリストを返すツールは、 単一の @context の下にある @graph にリストを格納した JSON-LD ドキュメントを返します。 結果を簡潔に保つため、 別の値の中にネストされた値（グラフ内の値を含む）では @type を省略します。

Schema.org は、人、住所、イベントなど、 表現したいさまざまなオブジェクトに対する標準的な語彙を提供しています。 また、JSON-LD は、人、AI、従来のソフトウェアのいずれにとっても便利なエンコード形式です。

このプロジェクトでは、Ontology を作成しました。 これは構造化データを扱うための Swift パッケージです。 iMCP ツールが返す型など、Apple のフレームワークに含まれる型のための 便利なイニシャライザーを備えています。

iMCP Helper

Apple は HomeKit フレームワークをネイティブの macOS アプリでは利用できるようにしておらず、 Mac Catalyst アプリでのみ利用できます。 そのため、Home サービスは別の Catalyst アプリ iMCP Helper で実行されます。 Apple は Developer ID アプリでの HomeKit の使用を許可していないため、 iMCP のリリースビルドにはヘルパーが含まれていません。 自分の Apple Developer アカウントを使ってビルドし、インストールしてください。

git clone https://github.com/mattt/iMCP.git
cd iMCP
Scripts/install-helper.sh

このスクリプトは、チームの開発用証明書でヘルパーに署名し、 /Applications にインストールします。 別のチーム、バンドル ID、またはインストール先ディレクトリを選択するには、--help を付けて実行してください。 Xcode でアカウントにサインインしている必要があります（Xcode > Settings > Accounts）。 また、ヘルパーはチームに登録された Mac でのみ実行できます。 無料の個人用チームで HomeKit を利用できるかは確認されていません。 次に、iMCP で Home を有効にしてください。 iMCP は /Applications 内のヘルパーを検出します。 別の場所にインストールした場合は、 Home を有効にするときに iMCP から選択を求められます。 または、Settings > Home で選択することもできます。 Home を有効にすると、 iMCP はヘルパーが起動していない場合に起動し、 ヘルパーは HomeKit へのアクセスを求めます。 初回は、ヘルパーのウィンドウに 7KQ2-M9XD のような8文字のペアリングコードと、 番号付きの手順が表示されます。 Copy Code をクリックし、 Open iMCP… をクリックして iMCP の「Pair with iMCP Helper」ウィンドウを開き、 コードを貼り付けて Pair をクリックします。 このボタンは URL imcp://pair を開きます。この URL にデータは含まれていません。 iMCP はこの URL を受け取ったときにペアリングウィンドウを開くだけです。 ヘルパーは、バンドル ID が co.dododo.iMCP のアプリのみでこの URL を開きます。 実行中のアプリを優先し、imcp スキームを宣言していないアプリでは開きません。 たとえば、別のバンドル ID で iMCP をビルドした場合など、該当するアプリがないときは、 代わりに Settings > Home で Pair… を選ぶようヘルパーが案内します。 ヘルパーのウィンドウがほかのウィンドウの背後にある場合は、 iMCP のウィンドウで Open iMCP Helper… をクリックしてください。 コードは一度だけ使用できます。 ペアリングすると、iMCP は新しいランダムキーをヘルパーに送信し、 両方のアプリがそのキーをキーチェーンに保存します。 コードを5回間違えると、ヘルパーに新しいコードが表示されます。 もう一度ペアリングするには、ヘルパーのウィンドウで Pair Again… をクリックして確認してください。 ヘルパーは iMCP との接続を終了し、新しいコードと同じ手順を表示します。 iMCP を終了した後もヘルパーは実行され続けます。 停止するには、アプリメニューから Quit iMCP Helper を選ぶか、Command-Q を押してください。 ウィンドウには起動エラーと権限エラーも表示されます。 Mac の iCloud アカウントにはホームへのアクセス権が必要です。 書き込みには、所有者または管理者の役割が必要な場合があります。

Sparkle は iMCP を更新しますが、ヘルパーは更新しません。 iMCP を更新した後は、 新しいバージョンに一致するタグからヘルパーを再ビルドしてください。

git fetch --tags
git checkout <version>
Scripts/install-helper.sh

古いバージョンのヘルパーは、アプリの Home ツールと互換性がない場合があります。

ヘルパーの開発用証明書とプロビジョニングプロファイルには有効期限があります。 通常はいずれも1年間有効ですが、 証明書のほうが先に期限切れになることがあります。 プロファイルの有効期限を確認するには、次を実行してください。

security cms -D -i "/Applications/iMCP Helper.app/Contents/embedded.provisionprofile" |
  plutil -extract ExpirationDate raw -o - -

証明書の有効期限を確認するには、次を実行してください。

codesign -d --extract-certificates=/tmp/imcp-helper-cert "/Applications/iMCP Helper.app"
openssl x509 -inform DER -in /tmp/imcp-helper-cert0 -noout -enddate

2つの日付のうち早いほうを過ぎると、ヘルパーが起動しなくなることがあります。 更新するには Scripts/install-helper.sh をもう一度実行してください。 古い証明書とプロファイルの期限が切れている場合、 このスクリプトによって Xcode が新しい証明書とプロファイルを作成できます。

初回実行時に、「PLA Update available」というエラーでプロビジョニングに失敗することがあります。 チームのアカウント所有者は、Apple Developer アカウントで 最新のプログラム使用許諾契約に同意する必要があります。 たとえば管理者以外のユーザーなど、/Applications に書き込めない場合は、 権限エラーによりインストールに失敗することがあります。 代わりに、スクリプトを --destination ~/Applications を付けて実行してください。 その後、iMCP からヘルパーの選択を求められます。

両方のアプリは、同じツール定義を Shared/Home/HomeTools.swift からコンパイルします。 ヘルパーは HomeKit を使ってツールを実装します。 アプリはループバックインターフェース上の MCP 接続を介して各呼び出しを転送するため、 通常のサービスとツールごとの切り替え設定が適用されます。 オブジェクト ID は HomeKit の UUID 文字列です。 インベントリツールは、include_values が true の場合にのみ特性の現在値を返します。 タイムアウトは5秒で、HomeKit の読み取りは同時に最大4件までです。 接続が失われた後、読み取り専用の呼び出しは1回再試行されます。 HomeKit がすでに書き込みを適用している可能性があるため、書き込みは再試行されません。 エラーには、再試行する前にホームの状態を確認するよう求めるメッセージが表示されます。 ヘルパーはローカル専用の DNS-SD インターフェイスで「_imcp-helper._tcp」をアドバタイズします。 iMCP は、ヘルパーを起動したかどうかにかかわらず、そこでヘルパーを検出します。 複数のヘルパーが実行中の場合、 iMCP は選択した場所にあるヘルパーを最初に試し、その後、ほかのヘルパーを試します。 接続では、ペアリング時のキーを事前共有キーとして TLS を使用するため、 キーを持たない接続は TLS ハンドシェイクに失敗します。 暗号スイートには ECDHE 鍵交換が追加されているため、 キーやコードが後から知られても、記録された接続の秘密は保たれます。 ペアリング接続では、PBKDF2 を使ってコードから導出したキーを使用します。 そのため、ペアリング中にヘルパーを装うプロセスがコードを推測するには、 一回ごとに時間がかかります。 以前のバージョンの iMCP でヘルパーをビルドした場合は、 ヘルパーを終了し、Scripts/install-helper.sh で再ビルドしてください。 iMCP は、現在のプロトコルバージョンを宣言していないヘルパーを拒否します。 iMCP で Home を有効にすると、 uv run Scripts/check-home.py <path-to-imcp-server> を実行して、 iMCP 経由で読み取り専用の統合チェックを行えます。

ヘルパーのビルド

iMCP スキームをビルドすると、 Scripts/build-helper.sh が実行されます。 このスクリプトは、専用の derived-data ディレクトリで Mac Catalyst 用の iMCP Helper スキームをビルドし、その生成物をアプリにコピーします。 ターゲット間の直接の依存関係ではヘルパーの iOS バリアントが選択されるため、 ネストされたビルドが必要です。 リリースビルドでは EMBED_HOME_HELPER = NO に設定され、ヘルパーは含まれません。

HomeKit のエンタイトルメントには、開発用証明書と HomeKit 機能を含むプロビジョニングプロファイルが必要です。 そのため、ネイティブの Debug アプリが署名なしであっても、 ヘルパーは Debug と Release の両方でチーム TTY35UM57S による自動署名を使用します。 別のチームでビルドするには、ヘルパーターゲットの 「Signing & Capabilities」タブでチームを変更してください。 新しいバンドル ID で最初に Mac Catalyst ビルドを行うと、 「Entitlement com.apple.developer.homekit not found and could not be included in profile」 というエラーが発生することがあります。 これは、自動プロビジョニングで iOS の実行先にのみ機能が登録されるためです。 Scripts/install-helper.sh は、iOS 用に一度ビルドしてから再試行することで、この問題に対処します。 手動で行う場合は、iOS 用にヘルパーを一度ビルドして登録してから、 Mac Catalyst 用にビルドしてください。

xcodebuild -scheme "iMCP Helper" -destination "generic/platform=iOS" \
  -allowProvisioningUpdates build
xcodebuild -scheme "iMCP Helper" -destination "platform=macOS,variant=Mac Catalyst" \
  -allowProvisioningUpdates build

CI では両方のアプリを署名なしでビルドします。 これによりコンパイルとパッケージ化は確認できますが、HomeKit にはアクセスできません。

xcodebuild -scheme iMCP -configuration Debug -destination "platform=macOS" \
  CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO \
  HELPER_CODE_SIGNING_ALLOWED=NO build

デバッグ

ローカルネットワークへのアクセスを許可する

imcp-server は Bonjour で iMCP アプリを検出するため、 ローカルネットワークへのアクセス許可が必要です。 imcp-server には、「システム設定」＞「プライバシーとセキュリティ」＞「ローカルネットワーク」に iMCP や、ターミナルなどの実行元アプリとは別の項目があります。 その項目がオフになっていると、 imcp-server はアプリを検出できず、 Bonjour サービスの検出がタイムアウトしたと報告します。

MCP Inspector の使用

iMCP とクライアント間のやり取りをデバッグするには、 Inspector ツールを使用できます （Node.js が必要です）。

1. ＞「サーバーコマンドをクリップボードにコピー」をクリックします

2. ターミナルを開き、次のコマンドを実行します

   # Download and run inspector package on imcp-server
   npx @modelcontextprotocol/inspector [paste-copied-command]
   
   # Open inspector web app running locally
   open http://127.0.0.1:6274
   

Inspector を使うと、クライアントと iMCP サーバー間のすべてのリクエストとレスポンスを確認できます。 プロトコルの仕組みを理解するのに役立ちます。

Companion の使用

Companion は、MCP サーバーのテストとデバッグに使えるユーティリティです （macOS 15 以降が必要です）。 サーバーのプロンプト、リソース、ツールを簡単に参照して操作できます。 iMCP に接続する手順は次のとおりです。

1. ＞「サーバーコマンドをクリップボードにコピー」をクリックします
2. Companion アプリをダウンロードして開きます
3. ツールバーの + ボタンをクリックして、MCP サーバーを追加します
4. フォームに入力します
   • 名前に「iMCP」と入力します
   • トランスポートとして「STDIO」を選択します
   • コピーした iMCP サーバーコマンドを貼り付けます
   • 「Add Server」をクリックします

• MCP に関する取り組みに対し、Justin Spahr-Summers (@jspahrsummers)、 David Soria Parra (@dsp-ant)、および Ashwin Bhat (@ashwin-ant) に感謝します。
• Messages アプリで使用される typedstream 形式のリバースエンジニアリングに対し、Christopher Sardegna (@ReagentX) に感謝します。

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。 詳しくは LICENSE ファイルをご覧ください。

法的事項

iMessage® は Apple Inc. の登録商標です。 このプロジェクトは Apple Inc. と提携、推奨、または後援関係にありません。