abm-mcp — Operate Apple Business from Claude through a gated MCP server

English summary (Japanese documentation follows below)

A Python MCP server that lets Claude work with the Apple Business API (OAuth 2 with an ES256 client assertion): devices, device management services, users, groups, apps, blueprints, configurations and audit events.

Design goals: safe by default, auditable, honest about what is verified.

• Read-only by default. Write tools are registered only with ABM_ENABLE_WRITE=1; destructive tools (release devices, delete blueprint/configuration/MDM server) additionally need ABM_ENABLE_DESTRUCTIVE=1. Tools that are disabled are not registered at all, so Claude cannot see them.

• Two-step execution for every change. The first call returns a preview and sends nothing. The change runs only with a one-time, expiring confirmation token bound to the exact arguments, and the client's own approval dialog still applies.

• Guardrails: per-operation device cap, ID format checks, requests limited to the API host and /v1/ paths, file reads (certificates, profiles) limited to one directory.

• Local audit log (JSON Lines, mode 600) of every preview, execution, success and failure. Tokens and request bodies are not logged.

• Secrets stay out of the code: the private key is passed by file path only.

• Verification status is documented: endpoints are marked as verified against Apple's documentation, inferred from third-party clients, or unverified. 29 automated tests run against a mock Apple server.

Status and limits. Built and verified against a live Apple Business organization (my own, personally contracted) — the real API, not only mocks. Live-verified so far: 8 read tools (device management services, devices, blueprints, user groups, organizational units, packages, Activation Lock status, MDM-enrolled devices) and one write tool (create_blueprint, through the preview/confirm flow); see the endpoint-confidence section (エンドポイントの確度) below. Not tested at scale: rate limits and batch-size limits are unverified, destructive tools have not been run live, and it has not been used by multiple administrators. Human approval cannot be distinguished from a click on the client's approval dialog. For production use I would add least-privilege API roles, centralized and searchable audit logs with approver identity, and enterprise secret management.

Disclosure. This project was designed by me (requirements and safety model) and built with Claude Code. It is an independent personal project and is not affiliated with, endorsed by, or supported by Apple Inc. or Anthropic. "Apple" and "Apple Business" are trademarks of Apple Inc.

License: MIT (see LICENSE). Provided as is, without warranty. This tool can change and delete data in an Apple Business organization when its write and destructive modes are enabled; use it on a dedicated test organization first.

日本語ドキュメント

実際の Apple Business（個人契約）に対して構築・動作検証した個人プロジェクトです。大規模運用（レート制限、1 回の操作の上限台数、複数管理者での利用）は未検証です。Apple Inc. とは無関係です。Claude Code を使って開発しました。

Apple Business の API（OAuth 2 + ES256 の client assertion）を MCP ツールとして公開します。 デバイス・デバイス管理サービス・ユーザー・グループ・アプリ・ブループリント・構成・監査イベントの参照と、 割り当て変更・ブループリント/構成の作成更新・削除などの変更ができます。

重要: 変更系・破壊的な操作は、必ず「プレビュー → 承認 → 実行」の 2 段階で動きます。 個人の検証用組織で、できること／できないことを試す用途を想定しています。

1. セットアップ（Mac）

Python 3.10 以上が必要です。 macOS 標準の python3（3.9）では動きません。 brew install python か uv で用意してください。

cd abm-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Apple Business 側の準備

1. 組織管理者でサインイン →「設定」＞「API」＞「APIアカウントを追加する」

2. 名前と役割を選びます。使いたい機能に対応する権限を持つ役割にしてください （デバイス、デバイス管理サービス、ユーザー、ユーザーグループ、組織のユニット、ブループリント、構成、パッケージ、アプリ、監査イベント）。

3. 「生成してダウンロード」で秘密鍵（.pem）を保存します。鍵は一度しか生成されません。

4. アカウントの「編集」画面で クライアントID（BUSINESSAPI.…）と キーID を控えます。

秘密鍵は専用の場所に置き、権限を絞ります（チャットや Git には絶対に載せないでください）。

mkdir -p ~/.abm-mcp/files && chmod 700 ~/.abm-mcp
mv ~/Downloads/<ダウンロードした鍵>.pem ~/.abm-mcp/abm-key.pem
chmod 600 ~/.abm-mcp/abm-key.pem

接続確認（Claude に繋ぐ前に）

export ABM_CLIENT_ID="BUSINESSAPI.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export ABM_KEY_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export ABM_PRIVATE_KEY_PATH="$HOME/.abm-mcp/abm-key.pem"
python -m abm_mcp.smoke

鍵の読み込み → トークン取得 → API 呼び出しを段階ごとに [OK]/[NG] で表示します（トークンは表示しません）。

Related MCP server: Apple Ecosystem MCP

2. Claude に登録する

Claude デスクトップアプリ

~/Library/Application Support/Claude/claude_desktop_config.json に追加して、アプリを再起動します。

{
  "mcpServers": {
    "apple-business": {
      "command": "/Users/<あなた>/abm-mcp/.venv/bin/python",
      "args": ["-m", "abm_mcp"],
      "env": {
        "ABM_CLIENT_ID": "BUSINESSAPI.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ABM_KEY_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "ABM_PRIVATE_KEY_PATH": "/Users/<あなた>/.abm-mcp/abm-key.pem"
      }
    }
  }
}

Claude Code

claude mcp add apple-business \
  -e ABM_CLIENT_ID=BUSINESSAPI.xxxx -e ABM_KEY_ID=xxxx \
  -e ABM_PRIVATE_KEY_PATH=$HOME/.abm-mcp/abm-key.pem \
  -- /Users/<あなた>/abm-mcp/.venv/bin/python -m abm_mcp

上の設定例は読み取り専用です（既定）。変更系ツールは ABM_ENABLE_WRITE=1、破壊的ツールはさらに ABM_ENABLE_DESTRUCTIVE=1 を追加したときだけ登録されます。影響を理解し、専用の検証用組織で試してから有効にしてください。

3. 環境変数

4. ツール

参照（常に有効） — check_connection, list_devices, get_device, get_device_applecare, get_device_activation_lock, get_device_assigned_server(_id), list_mdm_enrolled_devices, get_mdm_enrolled_device_details, list_mdm_servers, get_mdm_server, list_mdm_server_devices, get_activity, list_users, get_user, list_user_groups, get_user_group, list_user_group_members, list_organizational_units, get_organizational_unit, list_organizational_unit_members, list_apps, get_app, list_packages, get_package, list_blueprints, get_blueprint, get_blueprint_members, list_configurations, get_configuration, list_audit_events, api_get（任意の GET）

変更（ABM_ENABLE_WRITE=1） — assign_devices_to_mdm, unassign_devices_from_mdm, schedule_mdm_migration, update_mdm_migration_deadline, cancel_mdm_migration, create_blueprint, update_blueprint, add_to_blueprint, remove_from_blueprint, create_custom_configuration, update_custom_configuration, create_mdm_server, update_mdm_server

破壊的（ABM_ENABLE_DESTRUCTIVE=1 も必要） — release_devices, delete_blueprint, delete_configuration, delete_mdm_server

エンドポイントの確度

• 実環境で動作確認済み（個人契約の Apple Business）

  • 参照: list_mdm_servers、list_devices、list_blueprints、list_user_groups、list_organizational_units、list_packages、get_device_activation_lock、list_mdm_enrolled_devices

  • 変更: create_blueprint（プレビュー → 確認トークン → 実行の流れで確認）

  • これに伴い、以前は「第三者クライアントの記載から推定」としていた activationLockStatus、mdmDevices、organizationalUnits、userGroups、packages は、実環境で確認できました。

• Apple 公式ドキュメントで確認済み（実環境では未実行）: orgDeviceActivities（割り当て・解除・移行・解放）、apps、users、auditEvents、configurations、blueprints の relationships（追加）、OAuth 全般

• 推定: ブループリント関係の DELETE（本文は追加と同形式と仮定）。404/400 が出たら api_get で実際の応答を確認し、src/abm_mcp/tools.py のパスを直してください。

• 未確認: レート制限、1 回の割り当て操作の上限台数、update_blueprint に members を渡した時の挙動（追加か置換か）、監査イベントのフィルターのうち startTimestamp / endTimestamp 以外。破壊的ツールは実環境で実行していません。

「できること／できないこと」を調べる目的なので、これらの結果は Apple の仕様確認として役に立ちます。

5. 安全設計

• 2 段階実行: 変更系は confirm_token なしで呼ぶとプレビューだけ返し、何も送信しません。 トークンは「その引数の内容」に紐づき、1 回限り・期限付きです。引数を変えると無効になります。

• フラグで階層化: フラグが無効なツールはそもそも登録されません（Claude から見えません）。

• デバイス数の上限、ID の形式チェック（パス注入対策）、/v1/ 配下以外・API ホスト以外には送信しません。

• ファイル読み込みの制限: 証明書・構成プロファイルは ABM_FILES_DIR の中だけ。 悪意あるプロンプトで任意のファイルを Apple に送らせることはできません。

• 監査ログ: preview / execute / done / failed を記録（トークン・本文は記録しない）。

• 再試行: 401 はトークン再取得、429 は全メソッド、5xx は GET のみ（POST の二重実行を避ける）。

• MCP のツール注釈（読み取り専用／破壊的）が付くので、Claude 側の承認ダイアログも併用されます。

承認はあなたが内容を確認して与えてください。release_devices は組織への登録と自動登録の割り当てが外れ、 ブループリントからも除外されます。元に戻すには再登録が必要です。

6. トラブルシューティング

7. 開発・テスト

PYTHONPATH=src python3 -m unittest discover -s tests -v

Apple を模したサーバー（ES256 署名とクレームを実際に検証）に対して、認証・再試行・ページング・安全装置・ stdio での MCP 通信まで 29 件を確認します。実際の Apple Business 組織に対する動作確認は、 python -m abm_mcp.smoke で行ってください。