Macos-MCP

🍎 macOS-MCP

概要

macOS-MCP は、AI エージェントと macOS オペレーティングシステムをつなぐ、軽量なオープンソースの Model Context Protocol サーバーです。ファイルの移動、アプリケーションの操作、UI の操作、ブラウザーの自動化、システム操作などのタスクを通じて、LLM による macOS のシームレスな自動化を実現します。

対応オペレーティングシステム

• macOS 12（Monterey）
• macOS 13（Ventura）
• macOS 14（Sonoma）
• macOS 15（Sequoia）
• macOS 26（Tahoe）

主な機能

• あらゆる LLM で動作（ビジョン機能は任意）
  従来の自動化ツールとは異なり、macOS-MCP ではコンピュータービジョン、ファインチューニング済みモデル、専用のセットアップは不要です。Claude、GPT、Gemini など、あらゆる LLM でシームレスに動作します。

• macOS とのネイティブ連携
  Accessibility API を使用して、macOS の UI 要素をネイティブに操作します。回避策を使わずに、アプリを起動し、ウィンドウを操作し、ユーザー入力をシミュレートし、デスクトップの状態を取得します。

• 自動化のための豊富なツールセット
  キーボード／マウス操作、ウィンドウ管理、UI 状態の取得、アクセシビリティツリーからの操作可能な要素の抽出、AppleScript の実行に対応する包括的なツールキットです。

• 軽量でオープンソース
  依存関係は最小限で、MIT ライセンスの下、ソースコードをすべて公開しています。セットアップとデプロイが簡単です。

• スマートなコンテキスト認識
  アプリケーションの状態（Launchpad、Control Center、Spotlight）を自動的に検出します。メニューバー、Dock、デスクトップ、システム UI 要素をインテリジェントにスキャンします。

• カスタマイズと拡張が可能
  カスタムツールを簡単に追加したり、特定の自動化ニーズに合わせて動作を変更したりできます。

インストール

前提条件

• Python：3.11 以降
• UV パッケージマネージャー：pip install uv または curl -LsSf https://astral.sh/uv/install.sh | sh でインストール
• macOS：12（Monterey）以降
• アクセシビリティの権限：UI 要素の操作に必要です

クイックスタート

サーバーを直接実行します。

uvx macos-mcp serve

# Or with SSE/Streamable HTTP for network access
uvx macos-mcp serve --transport sse --host localhost --port 8000
uvx macos-mcp serve --transport streamable-http --host localhost --port 8000

今すぐ起動し、ログインのたびに自動起動するバックグラウンドサービスとして実行します。

macos-mcp install

# Or choose the HTTP transport and bind address explicitly
macos-mcp install --transport sse --host 127.0.0.1 --port 8000

これにより、~/Library/LaunchAgents/com.macos-mcp.server.plist に launchd Launch Agent がインストールされます。 削除するには macos-mcp uninstall を使用します。ログは ~/.macos-mcp/server.log および ~/.macos-mcp/server.error.log に書き込まれます。

トランスポートのオプション

必要な権限を付与する

macOS-MCP を正常に動作させるには、アクセシビリティと画面収録の権限が必要です。

アクセシビリティ権限

1. システム設定 → プライバシーとセキュリティ → アクセシビリティを開きます
2. 鍵のアイコンをクリックして認証します
3. 次のアプリケーションを追加します：
   • お使いのターミナルアプリケーション（Terminal、iTerm2、VS Code など）
   • Python（通常は/usr/bin/python3または UV が管理する Python バージョン）
   • UV（ローカルにインストールした場合は~/.local/bin/uv、それ以外の場合は UV が管理する Python 環境）
4. 権限を付与したら、ターミナルを再起動します

uvxユーザーの場合： uvxは UV のキャッシュから Python パッケージを実行するため、ターミナルアプリケーションと Python に権限を付与してください。

「+」選択画面でインタープリターのバイナリがグレー表示され、選択できない場合（UV が管理する Python のシンボリックリンクで発生する既知の問題です。例：.venv/bin/python3.12 → ~/.local/share/uv/python/...）：手動で追加しようとしないでください。代わりにサーバーを起動してください。v0.3.10 以降では、起動時にプロンプトオプションを指定してAXIsProcessTrustedWithOptionsを呼び出し、macOS のネイティブな確認ダイアログを表示して、実行中のプロセスを自動登録するよう求めます。ダイアログで許可し、サーバーを再起動してください。

アクセシビリティへのアクセス権をすでに持つ親プロセスからサブプロセスとして起動されており（特定の Claude Desktop 構成など）、権限チェックが誤って失敗する場合は、MACOS_MCP_SKIP_PERMISSION_CHECK=1を設定すると、終了する代わりに警告を出すようにチェックを変更できます。

画面収録の権限

Snapshotツールでスクリーンショットを撮影するには、画面収録の権限が必要です：

1. システム設定 → プライバシーとセキュリティ → 画面収録を開きます
2. 鍵のアイコンをクリックして認証します
3. 上記と同じアプリケーション（ターミナル、Python、UV）を追加します
4. 権限を付与したら、ターミナルを再起動します

注： Snapshotツールが動作しない場合は、システム設定で両方の権限が付与されていることを確認してください。

統合オプション

{
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve"]
    }
  }
}

macos-mcp install --transport streamable-http --host 127.0.0.1 --port 8000

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

# Start server with an auth key
macos-mcp install --transport streamable-http --host 0.0.0.0 --port 8000 \
  --auth-key "your-secret-token"

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer your-secret-token"
      ]
    }
  }
}

npm install -g @google/gemini-cli

{
  "theme": "Default",
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve"]
    }
  }
}

pi install git:github.com/CursorTouch/MacOS-MCP

/reload

pi -e git:github.com/CursorTouch/MacOS-MCP

git clone https://github.com/CursorTouch/MacOS-MCP.git
cd MacOS-MCP
uv sync
npm install
pi

export MACOS_MCP_ROOT=/path/to/MacOS-MCP

git clone https://github.com/CursorTouch/MacOS-MCP.git
cd MacOS-MCP
uv sync
tau

export MACOS_MCP_ROOT=/path/to/MacOS-MCP

MCP ツール

macOS-MCP は、デスクトップ自動化のための包括的なツールセットを提供します。

制限事項

• アクセシビリティの要件：システム設定で手動で権限を付与する必要があります
• アプリの互換性：一部のアプリケーションは、Accessibility API のサポートが限定的、またはサポートされていません
• パフォーマンスのばらつき：要素の多い複雑な UI では、走査に時間がかかることがあります
• テキスト入力：一部の特殊な入力フィールドでは、キー入力が正しく受け付けられない場合があります
• 認証：システムの認証ダイアログは操作できません

セキュリティとアクセス制御

認証

macos-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"

すべてのリクエストで Authorization: Bearer your_token ヘッダーが必要です。

IP 許可リスト

macos-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"

接続を指定された CIDR 範囲に制限します。

TLS/HTTPS

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

macos-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem

OAuth 2.0 + PKCE

静的 API キーの代わりに OAuth を使用する MCP クライアント（例：Claude Desktop）向け：

macos-mcp serve --transport streamable-http --host 0.0.0.0 \
  --ssl-certfile ~/.macos-mcp/cert.pem \
  --ssl-keyfile  ~/.macos-mcp/key.pem \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret

Claude Desktop の設定（mcp-remote ブリッジ経由。連携オプションを参照）：

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<host>:8000/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

注： Claude Desktop の claude_desktop_config.json は、 "type": "http" や "url" のエントリーを直接サポートしていません。上記のように mcp-remote を使用するか、Claude Desktop の UI で 設定 → コネクタ → カスタムコネクタを追加 からサーバーを追加してください。

OAuth サーバーが提供するエンドポイント：

• GET /.well-known/oauth-authorization-server — サーバーのメタデータ（RFC 8414）
• GET /oauth/authorize — Authorization Code + PKCE（S256 が必須）
• POST /oauth/token — トークン交換（クライアントシークレットが必須）
• POST /oauth/register — 無効。クライアントは事前にプロビジョニングする必要があります

動的クライアント登録は無効です。リダイレクト URI はループバックの http(s) のみに限られます。 認証キーと OAuth は併用できます。どちらも有効な Bearer トークンとして受け付けられます。

SSRF 保護

Scrape ツールは、プライベート IP、ループバック、リンクローカル、URL 内の認証情報、HTTP 以外のスキームをブロックします。

設定ファイル（~/.macos-mcp/config.toml）

毎回フラグを指定する代わりに、設定を ~/.macos-mcp/config.toml に保存できます。CLI フラグは常に設定ファイルの値より優先されます。

検索順序：

1. --config /path/to/config.toml
2. ~/.macos-mcp/config.toml

stdio — ローカルのみ。セキュリティ設定は不要です：

[server]
transport = "stdio"

SSE — 認証と IP 制限を使用したネットワークアクセス：

[server]
transport = "sse"
host      = "0.0.0.0"
port      = 8000
auth_key  = "your-secret-key"

[security]
ip_allowlist = ["192.168.1.0/24"]

Streamable HTTP — 認証と TLS を使用したネットワークアクセス（本番環境に推奨）：

[server]
transport    = "streamable-http"
host         = "0.0.0.0"
port         = 8000
auth_key     = "your-secret-key"
ssl_certfile = "cert.pem"   # resolved relative to ~/.macos-mcp/
ssl_keyfile  = "key.pem"

[security]
ip_allowlist        = ["192.168.1.0/24"]
oauth_client_id     = "my-client"      # optional — enables OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"

[tools]
exclude = ["Shell", "Scrape"]   # disable specific tools

使用可能なツール名：App、Shell、Snapshot、Click、Type、Scroll、Move、Shortcut、Wait、Scrape、Notification

証明書ファイルとキー ファイルを同じディレクトリに配置します：

~/.macos-mcp/
├── config.toml
├── cert.pem
└── key.pem

そのディレクトリに直接、自己署名証明書を生成します：

mkdir -p ~/.macos-mcp
openssl req -x509 -newkey rsa:4096 \
  -keyout ~/.macos-mcp/key.pem \
  -out ~/.macos-mcp/cert.pem \
  -days 365 -nodes

環境変数

すべての変数は任意です。claude_desktop_config.json の env キーで設定してください。

claude_desktop_config.json の例（認証 + TLS を使用するリモート接続）：

{
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
      "env": {
        "MACOS_MCP_AUTH_KEY": "your_token",
        "MACOS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
        "MACOS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
        "MACOS_MCP_SSL_KEYFILE": "/path/to/key.pem"
      }
    }
  }
}

テレメトリー

macOS-MCP は、サーバーの改善に役立てるため、匿名の使用状況データを収集します。個人情報、ツールの引数、出力が追跡されることはありません。

テレメトリーを無効にするには、ANONYMIZED_TELEMETRY を false に設定します。

{
  "mcpServers": {
    "macos-mcp": {
      "command": "uvx",
      "args": ["macos-mcp", "serve"],
      "env": { "ANONYMIZED_TELEMETRY": "false" }
    }
  }
}

セキュリティ

⚠️ 重要なセキュリティに関するお知らせ：macOS-MCP は、フルアクセスのアクセシビリティ API 権限で動作し、サンドボックス化されていない状態で実際のシステム操作を実行します。取り消しできない操作を行う可能性があります。

macOS-MCP を使用する前に：

• ✅ アクセシビリティ権限は信頼できるアプリケーションにのみ付与してください
• ✅ シェルコマンドはユーザーの全権限で実行されることを理解してください
• ✅ 実行前に AI が生成したアクションプランを確認してください
• ✅ 価値のないデータが保存された仮想マシンまたは隔離環境でのみ使用してください
• ✅ 本番環境に近い状況でテストする前にバックアップを作成してください

⛔ 以下では使用しないでください：

• 代替できないデータが保存されたシステム
• 本番マシンまたは共有システム
• コンプライアンス規制の対象となる環境（HIPAA、PCI など）

セキュリティに関する詳しいガイダンスは、SECURITY.md を参照してください。

貢献

貢献を歓迎します！以下については、CONTRIBUTING.md を参照してください。

• 開発環境のセットアップとコード標準
• テスト要件
• プルリクエストの手順
• コーディング規約（Ruff によるフォーマット、1 行あたり 100 文字）

ライセンス

macOS-MCP は MIT ライセンスのもとで公開されています。詳細は LICENSE を参照してください。

謝辞

macOS-MCP は、優れたオープンソースプロジェクトを利用して構築されています。

• PyObjC - Python と Objective-C のブリッジ
• Pillow - Python Imaging Library
• FastMCP - MCP フレームワーク
• macOS アクセシビリティ API（ApplicationServices）

引用

研究またはプロジェクトで macOS-MCP を使用する場合は、以下の形式で引用してください。

@software{macos-mcp,
  author       = {Jeomon George},
  title        = {macOS-MCP: Lightweight MCP Server for macOS Automation},
  year         = {2025},
  publisher    = {GitHub},
  url          = {https://github.com/Jeomon/macos-mcp}
}

質問や問題がありますか？ issue を作成するか、セキュリティに関する懸念については SECURITY.md を確認してください。