mcpField
A
Apple Contacts

Apple Contacts

ローカル
cupertino.mgcrea.io生産性5今日更新
リポジトリ公式サイト

Apple Contacts について

macOS の Apple Contacts 向け MCP サーバーです。ローカルのアドレス帳を使って電話番号やメールアドレスから名前を特定し、連絡先の検索・取得も行えます。書き込みは初期状態で無効です。

主な機能

  1. 01電話番号やメールアドレスを一括で名前に解決
  2. 02連絡先の検索・一覧表示・取得
  3. 03有効化時の連絡先作成・更新
  4. 04曖昧な一致は推測せず状態で通知

活用シーン

  1. 01電話番号やメールアドレスから連絡先を特定
  2. 02アドレス帳の項目を検索・確認
  3. 03書き込みを有効にして連絡先を作成・更新

MCP 対応

MCP サーバーとして、ハンドル解決、連絡先の検索・一覧・取得ツールを公開します。連絡先の書き込みツールは APPLE_CONTACTS_ALLOW_WRITES=1 の場合にのみ登録されます。

設定

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

mcp.json · 共通設定
{
  "mcpServers": {
    "mgcrea-mcp-apple-contacts": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-contacts"
      ],
      "env": {
        "APPLE_CONTACTS_ALLOW_WRITES": "<APPLE_CONTACTS_ALLOW_WRITES>"
      }
    }
  }
}
起動コマンドnpx -y @mgcrea/mcp-apple-contacts
設定が必要な環境変数
APPLE_CONTACTS_ALLOW_WRITESRegister the mutating tools. Off by default, and the gate decides whether the write tools exist at all rather than merely refusing — an agent with writes off cannot see them.

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

パッケージ
npm@mgcrea/mcp-apple-contacts1.31.0

ツール

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

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

詳細

@mgcrea/mcp-apple-contacts

macOS の Apple Contacts アドレス帳向け Model Context Protocol サーバーです。

非公式です。 Apple とは関係ありません。お使いの Mac にすでにあるアドレス帳を読み取ります。

存在理由：連絡先情報の解決

apple_contacts_resolve_handles は、電話番号とメールアドレスを名前に変換します。一度に最大 500 件まで処理できます。ここにあるほかの機能は、すべてそのためのものです。

ここでは、ファイル経由の処理ルールが速度ではなく機能に関するものだとわかります。Contacts のスクリプト辞書は約 65 ms で応答します。十分に高速ですが、この用途には使えません。電話番号を解決するには、保存されているすべての番号を対象にした、末尾の数字をキーとするインデックスが必要であり、Apple Events の往復を何度繰り返してもそれは得られません。そのため、読み取りには読み取り専用の SQLite を使い、Apple Events 経由の読み取りはありません。

947 個の電話番号キーと 295 個のメールアドレスキーを対象に、検索用インデックスを3 msで構築し、プロセスの終了まで保持します。

アクセス許可 — これはほかとは異なります

アクセス許可必要な操作備考
Contacts（独自）読み取り確認が求められます — ダイアログに応答すれば完了です
オートメーション → Contacts書き込みのみ読み取りには影響しません

Contacts は、この一連の機能のほかのものとは異なる方法で失敗します。フルディスクアクセスではなく、独自の TCC サービスで保護されており、フルディスクアクセスとは異なり、このアクセス許可は 確認を求めます。そのため、通常は「ダイアログに応答する」だけで解決し、「システム設定を開く」必要はありません。また、アドレス帳のためにディスク全体へのアクセスを許可するよう求めることもありません。

ツール

読み取り：diagnostics、resolve_handles、search_contacts、list_contacts、get_contact。

書き込みは APPLE_CONTACTS_ALLOW_WRITES=1 の場合にのみ登録されます。フラグがオフの場合、create_contact と update_contact は拒否されるのではなく、モデルから見えなくなります。

resolveHandles() はパッケージのルートからもエクスポートされるため、MCP を介さずに呼び出したい Node 内の呼び出し元から利用できます。

設定

変数デフォルト
APPLE_CONTACTS_ALLOW_WRITESオフ変更を行うツールを登録します。
APPLE_CONTACTS_PHONE_SUFFIX_DIGITS9末尾キーの桁数。6～15 です。
APPLE_CONTACTS_INDEX_MODEautoauto | ro | immutable | off。
APPLE_CONTACTS_STORE自動ストアのパスを明示的に指定します。
APPLE_CONTACTS_OSASCRIPT_TIMEOUT_MS30000初回実行時のアクセス許可ダイアログに対応できる値です。

注意点

  • ストアは複数あります。 locate.ts はリストを返し、すべてのクエリは各ストアに展開されます。実機では stores=2/2, contacts=421 となり、Apple Events の結果と正確に一致します。最初のストアだけを読み取るサーバーは、アカウントをひとつ黙って見落とします。
  • 末尾 9 桁のキーで、桁数は検索オブジェクト内に保持されます。そのため、インデックスとクエリの間で桁数が食い違うことはありません。実際のアドレス帳を使い、7、9、10 桁で自己結合して検証した結果、7 桁と 9 桁では同じように衝突し（947 個のキーのうち 10 個、1.1%）、10 桁では国内形式から E.164 形式への結合が失われる一方で、キーがひとつ欠落します。
  • 曖昧な結果はステータスとして扱い、推測はしません — resolved / unknown / ambiguous / shortcode。unknown はエラーではなく想定される結果だと、ツールの説明に記載されています。
  • Z_ENT で ABCDContact に絞り込みます。 これがないと、一覧表示ツールはグループを人として返します。
  • 書き込みが成功しても、変更が永続化されるとは限りません。 Contacts は変更を未保存のバッファーに保持するため、同じスクリプト内では変更後の値を読み戻せても、ストアには反映されないことがあります。各書き込みスクリプトは保存してから再読み込みします。

ライセンス

MIT。

コメント

Markdown 対応

MCP は初めてですか？

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

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