Apple Contacts

Apple Contacts MCP

macOS 上的 Apple Contacts MCP サーバーです。

連絡先へのアクセスを提供し、検索や宛先の解決に利用できます。メッセージを送信する前に、名前を電話番号またはメールアドレスに解決するために使用してください。

使用する場面

• 連絡先に特化したワークフロー
• メッセージ送信前の宛先の確認
• オールインワンサーバーとは分けて連絡先を検索する場合

できること

• 連絡先の一覧表示と検索
• 連絡先の詳細情報の取得
• メッセージの宛先の解決
• コンテキストに制約のあるクライアント向けのツール検出ヘルパー search_tools と get_tool_info
• 連絡先の作成、更新、削除
• 重複の検出と統合候補の提案（contacts_find_duplicates、contacts_suggest_merge_candidates）
• ラベル付きの電話番号とメールアドレスの編集
• ディレクトリリソースと宛先確認プロンプト
• ヘルスチェックと権限の確認：contacts_health、contacts_permission_guide、contacts_recheck_permissions

この Mac へのインストール

uvx apple-contacts-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

AI エージェントへのインストール

{
  "mcpServers": {
    "apple-contacts": {
      "command": "uvx",
      "args": ["apple-contacts-mcp"],
      "env": {
        "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage"
      }
    }
  }
}

claude mcp add --transport stdio --scope user apple-contacts -- uvx apple-contacts-mcp

安全モード

• safe_readonly
• safe_manage
• full_access

トランスポート

デフォルトかつ推奨のトランスポートは stdio です。代わりに Streamable HTTP で配信するには、APPLE_CONTACTS_MCP_TRANSPORT=streamable-http を設定します（APPLE_CONTACTS_MCP_HOST と APPLE_CONTACTS_MCP_PORT は任意です）。

検索の動作

名前と組織の検索には、Contacts.app のフィルタ付き検索を使用します。一致する名前がない場合は、アドレス帳全体をスキャンせずに空の結果を返します。数値と句読点を基本とする電話番号クエリでは、認識される内線番号の接尾辞（ext、ext.、extension、extn.、x、#、;ext=）や省略可能な tel: プレフィックスを含む場合、方式の値との照合のためにページ分割されたディレクトリへのフォールバックを引き続き利用します。@ を含むメールアドレスクエリでも同様です。内線番号の照合では、基本の電話番号と内線番号を別々に扱い、内線番号の完全一致を必須とし、ローカル番号の末尾部分との照合も許可します。宛先の解決では、一致する電話番号の方式を選択し、一致する方式が複数あり、それぞれが異なる場合は拒否します。

Contacts が返す制御文字や複雑な絵文字は、テキストを変更せずに Python 側でデコードされます。

macOS の権限

• 連絡先へのアクセスが必要です。
• contacts_health は、アクセス許可を要求したり連絡先を読み取ったりせずに、ネイティブの認証ステータスを読み取ります。permission_status は、許可済み、不明、拒否、確認失敗を区別します。AppleScript バックエンドは、Apple Events を送信せずに認証ステータスを不明として報告します。明示的な連絡先操作では、引き続き権限の確認が行われます。

起動チェックリスト

• uvx apple-contacts-mcp（またはクローン内の AppleContacts-MCP/start.sh）を MCP クライアントに追加します。
• クライアントを再読み込みまたは再接続し、連絡先ツール群をコンテキストに読み込みます。
• 最初に contacts_health を呼び出します。
• 連絡先へのアクセスがブロックされている場合は、contacts_permission_guide を呼び出します。
• macOS の権限を変更した後は、contacts_recheck_permissions を呼び出します。

プロンプトに関する注意事項

• tools/list は Contacts のツール一式をすべて返します。コンテキストに制約のあるクライアントは、まず search_tools を使い、次に必要な Contacts ツールについて get_tool_info を使えます。
• ユーザーが人名を指定した場合は、iMessage または Mail で操作する前に Contacts を実行してください。
• 操作する前に、名前、電話番号、またはメールアドレスで相手を特定してください。
• 一致する連絡先が複数ある場合は、送信する前に対象の人物を確認してください。
• 人物の情報を更新するときは、電話番号またはメールアドレスの一式を置き換える場合に限り、明示的な phones または emails 配列を渡してください。
• Messages または Mail で連絡する前に、連絡先にラベル付きの電話番号またはメールアドレスを登録してください。

関連項目

• Apple-Tools-MCP

Contacts へのネイティブアクセス

Contacts はデフォルトで CNContactStore を使用するため、読み取りと書き込みで Contacts.app の起動を待つ必要はありません。初回利用時には、パッケージに含まれる Swift ヘルパーを Xcode Command Line Tools でコンパイルし、署名済みアプリケーションバンドル Apple Contacts MCP Helper を ~/.apple-mcps/build にキャッシュします。別のビルドディレクトリを指定するには、APPLE_CONTACTS_MCP_HELPER_BUILD_DIR を設定してください。MCP サーバーを実行しているアプリに Contacts へのアクセス権がすでにある場合は、その権限が使われます。そうでない場合、macOS は Apple Contacts MCP Helper に Contacts へのアクセスを許可するかどうかを尋ねます。Calendar, Reminders and Contacts: who macOS asks about を参照してください。

以前のバックエンドを使うには、APPLE_CONTACTS_MCP_BACKEND=applescript を設定してください。ネイティブバックエンドは名と姓を直接返し、電話番号とメールアドレスの更新時の挙動を維持します。コレクションを省略するとそのまま保持され、[] を渡すと消去されます。連絡先メモには別途 macOS のエンタイトルメントが必要です。空でない note はネイティブ書き込みの前に拒否されます。メモには引き続き AppleScript バックエンドを利用できます。

このヘルパーは lookup_handles（電話番号またはメールアドレスの JSON 配列）にも対応しており、ディレクトリを一度走査して、それらを所有している可能性のある連絡先を返します。他のコマンドとは異なり、アクセス許可を求めることはありません。許可がない場合は PERMISSION_DENIED または AUTHORIZATION_UNKNOWN を返します。AppleContactsBridge.lookup_handles は、その連絡先一式に phone_matching の完全一致所有者ルールを適用します。Apple-Tools-MCP は、このヘルパーがすでにビルドされている場合に限り、これを使って Messages のハンドルの相手を特定します。これは MCP ツールとして公開されていません。

ネイティブヘルパーは、変更不可能なソーススナップショットを、完全な SHA-256 ハッシュを名前とするバンドルにコンパイルします。コンパイル中にソースが変更されると処理は拒否され、同時に行われるビルドによってインストール済みのバンドルが置き換えられることはありません。ソースのバージョンが異なる場合も、同じバンドル識別子を持つ別々の実行ファイルが保持されます。ヘルパーはアドホック署名されているため、ソースが変更されるアップデート後に macOS から再度確認を求められる場合があります。

このネイティブヘルパーは、JaumeAP/Apple-MCPs にある Jaume Puig の成果を基にしています。