macOS Automator MCP サーバー
概要
このプロジェクトは、macOS上でAppleScriptおよびJavaScript for Automation（JXA）スクリプトを実行できるModel Context Protocol（MCP）サーバー、 macos_automatorを提供します。IDでアクセスできる定義済みスクリプトのナレッジベースを備え、インラインスクリプト、スクリプトファイル、引数渡しをサポートしています。ナレッジベースは初回使用時に遅延読み込みされるため、サーバーの起動が高速になります。
Related MCP server: AppleScript MCP Server
利点
MCP 経由で AppleScript/JXA スクリプトをリモートで実行します。
一般的な macOS 自動化タスクに関する豊富で拡張可能なナレッジ ベースを活用します。
macOS アプリケーションとシステム機能をプログラムで制御します。
macOS 自動化をより大規模な AI 駆動型ワークフローに統合します。
前提条件
Node.js (バージョン 18.0.0 以上を推奨、
package.jsonエンジンを参照)。macOS。
重要な権限の設定:
この MCP サーバーを実行するアプリケーション (ターミナル、Node.js アプリケーションなど) には、サーバーが実行されている macOS マシン上での明示的なユーザー権限が必要です。
**自動化権限:**他のアプリケーション (Finder、Safari、メールなど) を制御します。
「システム設定」>「プライバシーとセキュリティ」>「自動化」に移動します。
リストでサーバーを実行しているアプリケーション (例: ターミナル) を見つけます。
制御する必要があるすべてのアプリケーションのチェックボックスがオンになっていることを確認します。
例を参照してください:
docs/automation-permissions-example.png(プレースホルダー画像)。
アクセシビリティ権限: 「システム イベント」を介した UI スクリプト用 (例: クリック、キーストロークのシミュレーション)。
「システム設定」>「プライバシーとセキュリティ」>「アクセシビリティ」に移動します。
サーバーを実行しているアプリケーション (例: ターミナル) をリストに追加し、そのチェックボックスがオンになっていることを確認します。
新しいアプリケーションを初めて操作したり、アクセシビリティ機能を使用したりしようとすると、事前承認されていてもmacOSの確認プロンプトが表示される場合があります。サーバー自体はこれらの権限を付与できません。
インストールと使用方法
このサーバーを実行する主な方法はnpx経由です。これにより、グローバルインストールを必要とせずに最新バージョンを使用できます。
MCP クライアントのmcp.json (または同等の構成) に次の構成を追加します。
ローカルで実行（開発または直接使用）
開発環境やクローンリポジトリから直接サーバーを実行したい場合は、提供されているstart.shスクリプトを使用することもできます。これは、ローカルで変更を加えたり、特定のバージョンを実行したりする場合に役立ちます。
リポジトリをクローンします。
git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed**MCP クライアントを構成します。**クローンされたリポジトリ内の
start.shスクリプトの絶対パスを指すように MCP クライアントの構成を更新します。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が作成され、これが公開パッケージのエントリポイントとなります。
提供されるツール
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スクリプト用です。このオブジェクトの値はスクリプト内のプレースホルダー（例：--
get_scripting_tips``--MCP_INPUT:yourKeyName）を置き換えます。get_scripting_tips のargumentsPromptを参照してください。値 (文字列、数値、ブール値、単純な配列/オブジェクト) は、AppleScript リテラルに変換されます。
その他のオプション:
timeout_seconds(整数、オプション、デフォルト: 60): 最大実行時間。output_format_mode(列挙型、オプション、デフォルト: 'auto'):osascript出力フォーマット フラグを制御します。'auto': (デフォルト) AppleScript (-sh) の場合は人間が読める形式を使用し、JXA の場合は直接出力 (-sフラグなし) を使用します。'human_readable':-sh(主に AppleScript 用の、人間が読める形式の出力) を強制します。'structured_error':-ss(主に 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 の自動化/アクセシビリティの権限に関する、以前と同じ重大な警告)。
例:
(インライン/ファイルパスの既存の例は引き続き有効です)
ID によるナレッジ ベース スクリプトの使用:
{ "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }input_data{ "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }
応答形式:
execute_scriptツールは次の形式で応答を返します。
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): 返される結果の最大数。
出力：
タイトル、説明、スクリプトの内容、言語、実行可能 ID (該当する場合)、引数プロンプト、メモなど、要求されたヒントを含む Markdown 形式の文字列を返します。
使用例:
すべてのカテゴリを一覧表示します:
{ "toolName": "get_scripting_tips", "input": { "list_categories": true } }「safari」カテゴリのヒントを取得します:
{ "toolName": "get_scripting_tips", "input": { "category": "safari" } }「クリップボード」に関連するヒントを検索:
{ "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }
主なユースケースと例
アプリケーション制御:
Safari から現在の URL を取得します:
{ "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }メール内の未読メールの件名を取得します:
{ "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 サーバー (ターミナルなど) を実行しているアプリケーションのシステム設定で、自動化とアクセシビリティの権限を再確認してください。
スクリプト構文エラー：
osascriptエラーはstderrまたはエラーメッセージに返されます。複雑なスクリプトは、まずスクリプトエディタ（AppleScript用）またはJXAランナーを使用してローカルでテストしてください。**タイムアウト:**スクリプトの実行時間が
timeout_seconds（デフォルトは60秒）を超えると、スクリプトは終了します。長時間実行されるスクリプトの場合は、タイムアウト値を増やしてください。ファイルが見つかりません:
script_path、MCP サーバーを実行しているユーザーがアクセスできる絶対 POSIX パスであることを確認してください。出力エラー/JXAの問題： JXAスクリプト、特にObjective-Cブリッジングを使用するスクリプトでは、
output_format_modeが'direct'または'auto'（デフォルト）に設定されていることを確認してください。human_readableなどのAppleScript固有のフォーマットフラグをJXAで使用すると、エラーが発生する可能性があります。AppleScriptの出力が正しく解析human_readableれない場合は、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 を参照してください。
発達
プロジェクトの構造、ビルド、テストの詳細については、 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 (frontmatter
id:から、またはファイル名/パスから生成されたもの) が埋め込みナレッジ ベースの ID と一致する場合、ローカル バージョンが埋め込みバージョンを上書きします。同様に、ローカルの
_shared_handlersディレクトリにある同じ名前と言語の共有ハンドラー (例:my_utility.applescript) は、同じカテゴリ内 (またはローカル KB の_shared_handlersのルートに配置した場合はグローバル) にある同じ名前と言語の埋め込みハンドラーを上書きします。ローカル KB の
_category_info.mdのカテゴリ説明は、同じカテゴリの埋め込み KB の説明よりも優先されることもあります。
これにより、コアアプリケーション ファイルを変更することなく、利用可能な自動化スクリプトとヒントをカスタマイズおよび拡張できるようになります。
貢献
貢献を歓迎します！問題やプルリクエストは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ファイルをご覧ください。