macOS Automator MCP サーバー
概要
このプロジェクトは、macOS上でAppleScriptおよびJavaScript for Automation(JXA)スクリプトを実行できるModel Context Protocol(MCP)サーバー、 macos_automator
を提供します。IDでアクセスできる定義済みスクリプトのナレッジベースを備え、インラインスクリプト、スクリプトファイル、引数渡しをサポートしています。ナレッジベースは初回使用時に遅延読み込みされるため、サーバーの起動が高速になります。
利点
- 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
スクリプトを使用することもできます。これは、ローカルで変更を加えたり、特定のバージョンを実行したりする場合に役立ちます。
- リポジトリをクローンします。
- **MCP クライアントを構成します。**クローンされたリポジトリ内の
start.sh
スクリプトの絶対パスを指すように MCP クライアントの構成を更新します。mcp.json
構成スニペットの例:重要:/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 によるナレッジ ベース スクリプトの使用:
input_data
で ID によるナレッジベース スクリプトを使用する:
応答形式:
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" } }
- Safari から現在の URL を取得します:
- ファイル システム操作:
- デスクトップ上のファイルを一覧表示します:
{ "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
または同様のコマンドで実行する場合): - 例 (
mcp-agentify
のようなenv
サポートする MCP ランナー経由で設定する場合):
- 値:
開発者向け
ローカル開発、プロジェクト構造 ( 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自動化機能を提供します。以下に、最も役立つ例をいくつかご紹介します。
ターミナル自動化
- 新しいターミナルタブでコマンドを実行します。
- sudoでコマンドを実行し、安全にパスワードを入力する
- 処理のためにコマンド出力をキャプチャする
ブラウザコントロール
- Chrome/Safari の自動化:
- ブラウザのコンテキストで JavaScript を実行します。
- ページコンテンツを抽出し、フォームを操作し、ワークフローを自動化します
- ウェブページのスクリーンショットを撮る
システムの相互作用
- システム設定を切り替えます(ダークモード、音量、ネットワーク):
- クリップボードの内容を取得/設定します:
- システムダイアログとアラートを開く/制御する
- システム通知の作成と管理
ファイル操作
- ファイル/フォルダーを作成、移動、操作します。
- テキストファイルの読み取りと書き込み:
- ディレクトリ内のファイルのリストとフィルタリング
- ファイルのメタデータとプロパティを取得する
アプリケーション統合
- カレンダー/リマインダー管理:
- Mail.app によるメール自動化:
- 音楽の再生を制御します:
- クリエイティブアプリ(Keynote、Pages、Numbers)を操作する
get_scripting_tips
ツールを使用して、カテゴリ別に整理された利用可能なすべての自動化機能を調べます。
ライセンス
このプロジェクトはMITライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。
local-only server
The server can only run on the client's local machine because it depends on local resources.
macOS 上で AppleScript および JavaScript for Automation スクリプトを実行するためのモデル コンテキスト プロトコル サーバーを提供します。事前定義されたスクリプトのナレッジ ベースを備え、macOS アプリケーションとシステム機能の自動化をサポートします。
Related Resources
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to build and test Xcode projects directly through a standardized interface, with capabilities for running tests, monitoring progress, and accessing logs in real-time.Last updated -29TypeScript
Appwrite MCP Serverofficial
AsecurityAlicenseAqualityA Model Context Protocol server that allows AI assistants to interact with Appwrite's API, providing tools to manage databases, users, functions, teams, and other resources within Appwrite projects.Last updated -8440PythonMIT License- AsecurityAlicenseAqualityA Model Context Protocol server that provides tools for Xcode-related operations, making it easier to work with iOS project management, building, testing, archiving, and deploying apps to both simulators and physical devices.Last updated -943JavaScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.Last updated -1448171JavaScriptMIT License