Macos Automator MCP

🚀 macOS Automator MCP Server

このプロジェクトは、Model Context Protocol (MCP) サーバー macos_automator を提供します。このサーバーを使用すると、macOS 上で AppleScript および JavaScript for Automation (JXA) スクリプトを実行できます。事前定義されたスクリプトの知識ベースが ID でアクセス可能で、インラインスクリプト、スクリプトファイル、および引数の渡しもサポートしています。知識ベースは初回使用時に遅延読み込みされるため、サーバーの起動が速くなります。

🚀 クイックスタート

このサーバーを使って、macOS 上で AppleScript や JXA スクリプトを実行することができます。まずは前提条件を満たし、インストールと設定を行ってください。

✨ 主な機能

• MCP を介して AppleScript/JXA スクリプトをリモートで実行できます。
• 豊富で拡張可能な、一般的な macOS 自動化タスクの知識ベースを利用できます。
• プログラムで macOS アプリケーションやシステム機能を制御できます。
• macOS の自動化をより大規模な AI 駆動のワークフローに統合できます。

📦 インストール

前提条件

• Node.js (バージョン >=18.0.0 を推奨、package.json の engines を参照)
• macOS

重要なパーミッション設定

• この MCP サーバーを実行するアプリケーション (例: Terminal、あなたの Node.js アプリケーション) は、サーバーが実行されている macOS マシンで明示的なユーザーパーミッションが必要です。
  • 自動化パーミッション: 他のアプリケーション (Finder、Safari、Mail など) を制御するために必要です。
    • 設定 > プライバシーとセキュリティ > 自動化 に移動します。
    • サーバーを実行しているアプリケーション (例: Terminal) をリストから見つけ、制御する必要のあるすべてのアプリケーションにチェックボックスをオンにします。
    • 例: docs/automation-permissions-example.png (プレースホルダー画像) を参照してください。
  • アクセシビリティパーミッション: "System Events" を介した UI スクリプト (例: クリックやキーストロークのシミュレート) を行うために必要です。
    • 設定 > プライバシーとセキュリティ > アクセシビリティ に移動します。
    • サーバーを実行しているアプリケーション (例: Terminal) をリストに追加し、チェックボックスをオンにします。
  • 初めて新しいアプリケーションを制御したり、アクセシビリティ機能を使用したりするときは、事前に許可を与えていても macOS の確認プロンプトが表示される場合があります。サーバー自体はこれらのパーミッションを付与することはできません。

インストール方法

このサーバーを実行する主な方法は npx を使用することです。これにより、グローバルインストールをすることなく最新バージョンを使用できます。

MCP クライアントの mcp.json (または同等の設定ファイル) に以下の設定を追加してください。

{
  "mcpServers": {
    "macos_automator": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/macos-automator-mcp@latest"
      ]
    }
  }
}

ローカルでの実行 (開発または直接使用用)

開発用、またはクローンしたリポジトリから直接サーバーを実行したい場合は、提供されている start.sh スクリプトを使用できます。これは、ローカルでの変更を行ったり、特定のバージョンを実行したい場合に便利です。

1. リポジトリをクローンします

   git clone https://github.com/steipete/macos-automator-mcp.git
   cd macos-automator-mcp
   npm install # 依存関係をインストールします
   

2. MCP クライアントを設定します MCP クライアントの設定を更新して、クローンしたリポジトリ内の start.sh スクリプトの絶対パスを指定します。

   例の mcp.json 設定スニペット:

   {
     "mcpServers": {
       "macos_automator_local": {
         "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh",
         "env": {
           "LOG_LEVEL": "DEBUG"
         }
       }
     }
   }
   

   重要: /absolute/path/to/your/cloned/macos-automator-mcp/start.sh を、あなたのシステム上の正しい絶対パスに置き換えてください。

   start.sh スクリプトは、コンパイルされたバージョンが見つからない場合は自動的に tsx を使用して TypeScript ソースを直接実行し、利用可能な場合は dist/ からコンパイルされたバージョンを実行します。LOG_LEVEL 環境変数を尊重します。

   開発者向けの注意: start.sh スクリプトは、実行前に既存のコンパイル済みの dist/server.js を削除するように変更すると (例: rm -f dist/server.js を追加する)、tsx を介して src/ ディレクトリから最新の TypeScript コードを常に実行するように設計されています。これは、古いビルドによる問題を防ぐための開発に最適です。本番環境でのデプロイ (例: npm に公開される場合) では、通常、ビルドプロセスによって確定的な dist/server.js が作成され、それが公開されたパッケージのエントリポイントになります。

💻 使用例

基本的な使用法

以下は、execute_script ツールを使って Safari の現在の URL を取得する例です。

{
  "input": {
    "script_content": "tell application \"Safari\" to get URL of front document"
  }
}

高度な使用法

知識ベースからスクリプトを参照し、引数を渡す例です。

{
  "toolName": "execute_script",
  "input": {
    "kb_script_id": "finder_create_folder_at_path",
    "input_data": {
      "folder_name": "New MCP Folder",
      "parent_path": "~/Desktop"
    }
  }
}

📚 詳細ドキュメント

提供されるツール

1. execute_script

macOS 上で AppleScript または JavaScript for Automation (JXA) スクリプトを実行します。スクリプトは、インラインコンテンツ (script_content)、絶対ファイルパス (script_path)、または組み込みの知識ベースから一意の kb_script_id を参照して提供できます。

スクリプトのソース (排他的):

• script_content (文字列): 生のスクリプトコード。
• script_path (文字列): スクリプトファイルの絶対 POSIX パス (例: .applescript, .scpt, .js)。
• kb_script_id (文字列): サーバーの知識ベースからの事前定義されたスクリプトの ID。利用可能なスクリプト ID とその機能を発見するには、get_scripting_tips ツールを使用してください。

言語指定:

• language (列挙型: 'applescript' | 'javascript', オプション): 言語を指定します。
  • kb_script_id を使用する場合、言語は知識ベースのスクリプトから推測されます。
  • script_content または script_path を使用し、language が省略された場合、デフォルトは 'applescript' です。

スクリプトへの入力の渡し方:

• arguments (文字列の配列, オプション):
  • script_path の場合: スクリプトの on run argv (AppleScript) または run(argv) (JXA) ハンドラーに標準引数として渡されます。
  • kb_script_id の場合: 事前定義されたスクリプトが位置指定の文字列引数を受け取るように設計されている場合に使用されます (例: --MCP_ARG_1, --MCP_ARG_2 のようなプレースホルダーを置き換えます)。get_scripting_tips のスクリプトの argumentsPrompt を確認してください。
• input_data (JSON オブジェクト, オプション):
  • 主に、名前付きの構造化された入力を受け取るように設計された kb_script_id スクリプト用です。
  • このオブジェクトの値は、スクリプト内のプレースホルダーを置き換えます (例: --MCP_INPUT:yourKeyName)。get_scripting_tips の argumentsPrompt を参照してください。
  • 値 (文字列、数値、ブール値、単純な配列/オブジェクト) は、AppleScript のリテラル相当に変換されます。

その他のオプション:

• timeout_seconds (整数, オプション, デフォルト: 60): 最大実行時間。
• output_format_mode (列挙型, オプション, デフォルト: 'auto'): osascript の出力形式フラグを制御します。
  • 'auto': (デフォルト) AppleScript では人間が読みやすい形式 (-s h) を使用し、JXA では直接出力 ( -s フラグなし) を使用します。
  • 'human_readable': -s h を強制的に使用します (主に AppleScript の人間が読みやすい出力)。
  • 'structured_error': -s s を強制的に使用します (主に AppleScript の構造化されたエラー報告)。
  • 'structured_output_and_error': -s ss を強制的に使用します (主に AppleScript のメイン結果とエラーの構造化された出力)。
  • 'direct': -s フラグを使用しません (JXA で推奨、auto モードでの JXA の動作も同じ)。
• include_executed_script_in_output (ブール値, オプション, デフォルト: false): true の場合、出力に実行された完全なスクリプトコンテンツ (知識ベースのスクリプトの場合はプレースホルダー置換後) またはスクリプトパスが含まれます。これは、出力コンテンツ配列の追加のテキスト部分として追加されます。
• include_substitution_logs (ブール値, オプション, デフォルト: false): true の場合、知識ベースのスクリプトに対して行われたプレースホルダー置換の詳細なログが出力に含まれます。これは、input_data と arguments がどのように処理されてスクリプトに挿入されるかをデバッグするのに役立ちます。ログは、成功時にはスクリプト出力の前に追加され、失敗時にはエラーメッセージに追加されます。
• report_execution_time (ブール値, オプション, デフォルト: false): true の場合、フォーマットされたスクリプト実行時間の追加メッセージがレスポンスコンテンツ配列に含まれます。

セキュリティ警告と macOS パーミッション: (以前と同じ重要な警告: 任意のスクリプトの実行と macOS の自動化/アクセシビリティパーミッションに関する警告)

レスポンス形式: execute_script ツールは、以下の形式のレスポンスを返します。

{
  content: Array<{
    type: 'text';
    text: string;
  }>;
  isError?: boolean;
}

• content: スクリプト出力を含むテキストコンテンツアイテムの配列
• isError: (ブール値, オプション) スクリプトの実行にエラーが発生した場合に true に設定されます。このフラグは、以下の場合に設定されます。
  • スクリプトの出力 (stdout) が "Error" で始まる場合 (大文字小文字を区別しません)
  • これにより、クライアントは出力テキストを解析することなく、実行が失敗したことを簡単に判断できます。

2. get_scripting_tips

サーバーの知識ベースから AppleScript/JXA のヒント、例、および実行可能なスクリプトの詳細を取得します。利用可能なスクリプト、その機能、および execute_script (特に kb_script_id) での使用方法を発見するのに役立ちます。

引数:

• list_categories (ブール値, オプション, デフォルト: false): true の場合、利用可能な知識ベースのカテゴリのリストとその説明のみを返します。他のパラメーターを上書きします。
• category (文字列, オプション): 特定のカテゴリ ID (例: "finder", "safari") でヒントをフィルタリングします。
• search_term (文字列, オプション): ヒントのタイトル、説明、スクリプトコンテンツ、キーワード、または ID 内でキーワードを検索します。
• refresh_database (ブール値, オプション, デフォルト: false): true の場合、リクエストを処理する前にディスクから知識ベース全体を再読み込みします。これは、知識ベースファイルをアクティブに変更していて、サーバーを再起動せずに最新バージョンを使用したい場合の開発中に便利です。
• limit (整数, オプション, デフォルト: 10): 返す結果の最大数。

出力:

• 要求されたヒントを含む Markdown 形式の文字列が返されます。これには、タイトル、説明、スクリプトコンテンツ、言語、実行可能な ID (該当する場合)、引数プロンプト、およびメモが含まれます。

主要な使用例

アプリケーション制御

• Safari から現在の URL を取得する: { "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }
• Mail で未読メールの件名を取得する: { "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }

ファイルシステム操作

• デスクトップ上のファイルをリストする: { "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }
• 新しいフォルダを作成する: { "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }

システムインタラクション

• システム通知を表示する: { "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }
• システム音量を設定する: { "input": { "script_content": "set volume output volume 50" } } (0-100)
• 現在のクリップボードの内容を取得する: { "input": { "script_content": "the clipboard" } }

トラブルシューティング

• パーミッションエラー: スクリプトがアプリを制御したり、UI アクションを実行したりできない場合は、MCP サーバーを実行しているアプリケーション (例: Terminal) のシステム設定で自動化とアクセシビリティのパーミッションを再確認してください。
• スクリプト構文エラー: osascript のエラーは stderr またはエラーメッセージに返されます。複雑なスクリプトは、最初に Script Editor (AppleScript 用) または JXA ランナーを使用してローカルでテストしてください。
• タイムアウト: スクリプトが timeout_seconds (デフォルト 60 秒) より長い時間をかける場合、実行が中止されます。長時間実行されるスクリプトの場合は、タイムアウトを増やしてください。
• ファイルが見つからない: script_path が MCP サーバーを実行しているユーザーがアクセス可能な絶対 POSIX パスであることを確認してください。
• 不正な出力/JXA の問題: JXA スクリプト、特に Objective-C ブリッジを使用するものの場合は、output_format_mode を 'direct' または 'auto' (デフォルト) に設定してください。AppleScript 固有のフォーマットフラグ (例: human_readable) を JXA で使用するとエラーが発生する場合があります。AppleScript の出力が正しく解析されない場合は、structured_output_and_error または structured_error を試してみてください。

環境変数による設定

• LOG_LEVEL: サーバーのログレベルを設定します。

  • 値: DEBUG, INFO, WARN, ERROR
  • 例: LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest

• KB_PARSING: 知識ベース (スクリプトのヒント) が解析されるタイミングを制御します。

  • 値:
    • lazy (デフォルト): 知識ベースは、get_scripting_tips への最初のリクエスト時、または execute_script で kb_script_id が使用されたときに解析されます。これにより、サーバーの起動が速くなります。
    • eager: 知識ベースはサーバー起動時に解析されます。これにより、起動時間が若干増える場合がありますが、知識ベースがすぐに利用可能になり、解析エラーが早期に検出されます。
  • 例 (start.sh または同様のものを使用して実行する場合):

    KB_PARSING=eager ./start.sh
    

  • 例 ( mcp-agentify のような env をサポートする MCP ランナーを介して設定する場合):

    {
      "env": {
        "LOG_LEVEL": "INFO",
        "KB_PARSING": "eager"
      }
    }
    

開発者向け情報

ローカル開発の詳細な手順、プロジェクト構造 ( knowledge_base を含む)、および貢献ガイドラインについては、DEVELOPMENT.md を参照してください。

ローカルの知識ベース

組み込みの知識ベースに、独自のローカルヒントと共有ハンドラーを追加することができます。このリポジトリの knowledge_base と同じディレクトリ構造 (またはそのサブセット) を作成してください。

デフォルトでは、アプリケーションは ~/.macos-automator/knowledge_base でこのローカルの知識ベースを探します。LOCAL_KB_PATH 環境変数を設定することで、このパスをカスタマイズできます。

例: あなたのローカルの知識ベースが /Users/yourname/my-custom-kb にあるとします。 環境変数を設定します: export LOCAL_KB_PATH=/Users/yourname/my-custom-kb

または、バリデータースクリプトを実行する場合は、--local-kb-path 引数を使用できます: npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb

構造と上書き:

• あなたのローカルの知識ベースは、メインの knowledge_base のカテゴリ構造を反映する必要があります (例: 01_applescript_core, 05_web_browsers/safari など)。
• 新しい .md ヒントファイルや _shared_handlers (例: .applescript または .js ファイル) を追加できます。
• あなたのローカルの知識ベースのヒント ID (フロントマターの id: またはファイル名/パスから生成されたもの) が、組み込みの知識ベースの ID と一致する場合、あなたのローカルバージョンが組み込みのものを 上書き します。
• 同様に、あなたのローカルの _shared_handlers ディレクトリ内の同じ名前と言語の共有ハンドラー (例: my_utility.applescript) は、同じカテゴリ内 (またはローカルの知識ベースの _shared_handlers のルートに配置した場合はグローバルに) の同じ名前と言語の組み込みのものを上書きします。
• あなたのローカルの知識ベースの _category_info.md からのカテゴリ説明も、同じカテゴリの組み込みの知識ベースのものを上書きすることができます。

これにより、コアアプリケーションファイルを変更することなく、利用可能な自動化スクリプトとヒントをカスタマイズおよび拡張できます。

貢献

貢献は大歓迎です！GitHub リポジトリに問題やプルリクエストを送信してください。

自動化機能

このサーバーは、AppleScript と JavaScript for Automation (JXA) を通じて強力な macOS 自動化機能を提供します。以下はいくつかの便利な例です。

ターミナル自動化

• 新しいターミナルタブでコマンドを実行する:

  { "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }
  

• sudo でコマンドを実行し、パスワードを安全に提供する
• コマンドの出力をキャプチャして処理する

ブラウザ制御

• Chrome/Safari の自動化:

  { "input": { "kb_script_id": "chrome_open_url_new_tab_profile", "input_data": { "url": "https://example.com", "profile_name": "Default" } } }
  

  { "input": { "kb_script_id": "safari_get_front_tab_url" } }
  

• ブラウザコンテキストで JavaScript を実行する:

  { "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }
  

• ページコンテンツを抽出し、フォームを操作し、ワークフローを自動化する
• ウェブページのスクリーンショットを撮る

システムインタラクション

• システム設定 (ダークモード、音量、ネットワーク) を切り替える:

  { "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }
  

• クリップボードの内容を取得/設定する:

  { "input": { "kb_script_id": "system_clipboard_get_file_paths" } }
  

• システムダイアログやアラートを開く/制御する
• システム通知を作成し、管理する

ファイル操作

• ファイル/フォルダを作成、移動、操作する:

  { "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }
  

• テキストファイルを読み書きする:

  { "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }
  

• ディレクトリ内のファイルをリストし、フィルタリングする
• ファイルのメタデータやプロパティを取得する

アプリケーション統合

• カレンダー/リマインダーの管理:

  { "input": { "kb_script_id": "calendar_create_event", "input_data": { "title": "Meeting", "start_date": "2023-06-01 10:00", "end_date": "2023-06-01 11:00" } } }
  

• Mail.app でのメール自動化:

  { "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }
  

• 音楽再生を制御する:

  { "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }
  

• クリエイティブアプリ (Keynote、Pages、Numbers) を操作する

get_scripting_tips ツールを使用して、カテゴリ別にすべての利用可能な自動化機能を探索してください。

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。