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 (または同等の構成) に次の構成を追加します。

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

ローカルで実行（開発または直接使用）

開発環境やクローンリポジトリから直接サーバーを実行したい場合は、提供されている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) スクリプトを実行します。スクリプトは、インラインコンテンツ ( scriptContent )、絶対ファイルパス ( scriptPath )、または固有のkbScriptIdを使用して組み込みナレッジベースからスクリプトを参照することによって提供できます。

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

scriptContent (文字列): 生のスクリプトコード。
scriptPath (文字列): スクリプトファイルへの絶対 POSIX パス (例: .applescript 、 .scpt 、 .js )。
kbScriptId (文字列): サーバーのナレッジベースから取得された定義済みスクリプトのID。利用可能なスクリプトIDとその機能を確認するには、 get_scripting_tipsツールを使用してください。

言語仕様:

language (列挙型: 'applescript' | 'javascript'、オプション): 言語を指定します。
- kbScriptIdを使用する場合、言語はナレッジベーススクリプトから推測されます。
- scriptContentまたはscriptPathを使用し、 language省略すると、デフォルトで 'applescript' になります。

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

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

その他のオプション:

timeoutSeconds (整数、オプション、デフォルト: 30): 最大実行時間。
useScriptFriendlyOutput (ブール値、オプション、デフォルト: false): 特にリストやレコードの場合、より構造化された出力を実現するためにosascript -ssフラグを使用します。
includeExecutedScriptInOutput (ブール値、オプション、デフォルト: false): true の場合、出力にはスクリプトの全内容（ナレッジベーススクリプトのプレースホルダ置換後）または実行されたスクリプトのパスが含まれます。これは、出力コンテンツ配列に追加テキストとして追加されます。
includeSubstitutionLogs (ブール値、オプション、デフォルト: false): true の場合、ナレッジベーススクリプトで実行されたプレースホルダ置換の詳細なログが出力に含まれます。これは、 inputDataとargumentsどのように処理され、スクリプトに挿入されるかをデバッグするのに役立ちます。ログは、成功した場合はスクリプト出力の先頭に追加され、失敗した場合はエラーメッセージの末尾に追加されます。

セキュリティ警告と macOS の権限: (任意のスクリプトの実行と macOS の自動化/アクセシビリティの権限に関する、以前と同じ重大な警告)。

例:

(インライン/ファイルパスの既存の例は引き続き有効です)
ID によるナレッジベーススクリプトの使用:
{ "toolName": "execute_script", "input": { "kbScriptId": "safari_get_active_tab_url", "timeoutSeconds": 10 } }
inputDataで ID によるナレッジベーススクリプトを使用する:
{ "toolName": "execute_script", "input": { "kbScriptId": "finder_create_folder_at_path", "inputData": { "folderName": "New MCP Folder", "parentPath": "~/Desktop" } } }

2. `get_scripting_tips`

サーバーのナレッジベースからAppleScript/JXAのヒント、例、実行可能なスクリプトの詳細を取得します。利用可能なスクリプト、その機能、 execute_script （特にkbScriptId ）での使用方法を確認するのに役立ちます。

引数:

listCategories （ブール値、オプション、デフォルト：false）: trueの場合、利用可能なナレッジベースカテゴリとその説明のリストのみを返します。他のパラメータを上書きします。
category (文字列、オプション): 特定のカテゴリ ID (例: "finder"、"safari") でヒントをフィルターします。
searchTerm (文字列、オプション): ヒントのタイトル、説明、スクリプトコンテンツ、キーワード、または ID 内でキーワードを検索します。
refreshDatabase (ブール値、オプション、デフォルト: false): true の場合、リクエストを処理する前に、ディスクからナレッジベース全体を強制的にリロードします。これは、開発中にナレッジベースファイルを頻繁に変更し、サーバーを再起動せずに最新バージョンが使用されるようにしたい場合に便利です。

出力：

タイトル、説明、スクリプトの内容、言語、実行可能 ID (該当する場合)、引数プロンプト、メモなど、要求されたヒントを含む Markdown 形式の文字列を返します。

使用例:

すべてのカテゴリを一覧表示します: { "toolName": "get_scripting_tips", "input": { "listCategories": true } }
「safari」カテゴリのヒントを取得します: { "toolName": "get_scripting_tips", "input": { "category": "safari" } }
「クリップボード」に関連するヒントを検索: { "toolName": "get_scripting_tips", "input": { "searchTerm": "clipboard" } }

主なユースケースと例

アプリケーション制御:
- Safari から現在の URL を取得します: { "scriptContent": "tell application \"Safari\" to get URL of front document" }
- メール内の未読メールの件名を取得します: { "scriptContent": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" }
ファイルシステム操作:
- デスクトップ上のファイルを一覧表示します: { "scriptContent": "tell application \"Finder\" to get name of every item of desktop" }
- 新しいフォルダを作成します: { "scriptContent": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" }
システムの相互作用:
- システム通知を表示します: { "scriptContent": "display notification \"Important Update!\" with title \"System Alert\"" }
- システム音量の設定: { "scriptContent": "set volume output volume 50" } (0-100)
- 現在のクリップボードの内容を取得します: { "scriptContent": "the clipboard" }

トラブルシューティング

**権限エラー:**スクリプトがアプリを制御したり UI アクションを実行したりできない場合は、MCP サーバー (ターミナルなど) を実行しているアプリケーションのシステム設定で、自動化とアクセシビリティの権限を再確認してください。
スクリプト構文エラー： osascriptエラーはstderrまたはエラーメッセージに返されます。複雑なスクリプトは、まずスクリプトエディタ（AppleScript用）またはJXAランナーを使用してローカルでテストしてください。
**タイムアウト:**スクリプトの実行時間がtimeoutSeconds （デフォルトは30秒）を超えると、スクリプトは終了します。長時間実行されるスクリプトの場合は、タイムアウト値を増やしてください。
ファイルが見つかりません: scriptPath 、MCP サーバーを実行しているユーザーがアクセスできる絶対 POSIX パスであることを確認してください。
**出力が正しくありません:**デフォルトの人間が判読できる出力が解析に適していない場合は (特にリストやレコードの場合)、 useScriptFriendlyOutput: trueを試してください。

環境変数による設定

LOG_LEVEL : サーバーのログレベルを設定します。
- 値: DEBUG 、 INFO 、 WARN 、 ERROR
- 例: LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest
KB_PARSING : ナレッジベース (スクリプトのヒント) を解析するタイミングを制御します。
- 値:
  - lazy （デフォルト）：ナレッジベースは、 get_scripting_tipsへの最初のリクエスト時、またはexecute_scriptでkbScriptIdが使用された際に解析されます。これにより、サーバーの起動が高速化されます。
  - 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自動化機能を提供します。以下に、最も役立つ例をいくつかご紹介します。

ターミナル自動化

新しいターミナルタブでコマンドを実行します。
{ "kbScriptId": "terminal_app_run_command_new_tab", "inputData": { "command": "ls -la" } }
sudoでコマンドを実行し、安全にパスワードを入力する
処理のためにコマンド出力をキャプチャする

ブラウザコントロール

Chrome/Safari の自動化:
{ "kbScriptId": "chrome_open_url_new_tab_profile", "inputData": { "url": "https://example.com", "profileName": "Default" } }
{ "kbScriptId": "safari_get_front_tab_url" }
ブラウザのコンテキストで JavaScript を実行します。
{ "kbScriptId": "chrome_execute_javascript", "inputData": { "javascript": "document.title" } }
ページコンテンツを抽出し、フォームを操作し、ワークフローを自動化します
ウェブページのスクリーンショットを撮る

システムの相互作用

システム設定を切り替えます（ダークモード、音量、ネットワーク）：
{ "kbScriptId": "systemsettings_toggle_dark_mode_ui" }
クリップボードの内容を取得/設定します:
{ "kbScriptId": "system_clipboard_get_file_paths" }
システムダイアログとアラートを開く/制御する
システム通知の作成と管理

ファイル操作

ファイル/フォルダーを作成、移動、操作します。
{ "kbScriptId": "finder_create_new_folder_desktop", "inputData": { "folderName": "My Project" } }
テキストファイルの読み取りと書き込み:
{ "kbScriptId": "fileops_read_text_file", "inputData": { "filePath": "~/Documents/notes.txt" } }
ディレクトリ内のファイルのリストとフィルタリング
ファイルのメタデータとプロパティを取得する

アプリケーション統合

カレンダー/リマインダー管理:
{ "kbScriptId": "calendar_create_event", "inputData": { "title": "Meeting", "startDate": "2023-06-01 10:00", "endDate": "2023-06-01 11:00" } }
Mail.app によるメール自動化:
{ "kbScriptId": "mail_send_email_direct", "inputData": { "recipient": "user@example.com", "subject": "Hello", "body": "Message content" } }
音楽の再生を制御します:
{ "kbScriptId": "music_playback_controls", "inputData": { "action": "play" } }
クリエイティブアプリ（Keynote、Pages、Numbers）を操作する

get_scripting_tipsツールを使用して、カテゴリ別に整理された利用可能なすべての自動化機能を調べます。

ライセンス

このプロジェクトはMITライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。

macOS Automator MCP Server

Integrations