applescript-mcp MCP Server

applescript-mcp MCP サーバー

LLM アプリケーションが AppleScript を通じて macOS と連携できるようにする、Model Context Protocol サーバーです。 このサーバーは、AI アプリケーションがシステム機能を制御したり、ファイルを管理したり、通知を処理したりするための標準インターフェースを提供します。

機能

• 🗓️ カレンダー管理（イベント、リマインダー）
• 📋 クリップボード操作
• 🔍 Finder 連携
• 🔔 システム通知
• ⚙️ システム制御（音量、ダークモード、アプリ）
• 📟 iTerm ターミナル連携
• 📬 メール（メールの新規作成、メール一覧の取得、メールの取得）
• 🔄 ショートカットの自動化
• 💬 メッセージ（チャット一覧の取得、メッセージの取得、メッセージの検索、メッセージの送信）
• 🗒️ メモ（書式付きメモの作成、メモ一覧の取得、メモの検索）
• 📄 Pages（書類の作成）

予定している機能

• 🧭 Safari（Safari で開く、ページの内容を保存する、選択中のページ／タブを取得する）
• ✅ リマインダー（作成、取得）

前提条件

• macOS 10.15 以降
• Node.js 18 以降

利用可能なカテゴリ

カレンダー

コマンド	説明	パラメーター
add	カレンダーイベントを作成	title、startDate、endDate、calendar（省略可）
list	今日のイベント一覧を取得	なし

例

// Create a new calendar event
Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour

// List today's events
What events do I have scheduled for today?

クリップボード

コマンド	説明	パラメーター
set_clipboard	クリップボードにコピー	content
get_clipboard	クリップボードの内容を取得	なし
clear_clipboard	クリップボードを消去	なし

例

// Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard

// Get clipboard contents
What's currently in my clipboard?

// Clear clipboard
Clear my clipboard

Finder

コマンド	説明	パラメーター
get_selected_files	選択中のファイルを取得	なし
search_files	ファイルを検索	query、location（省略可）
quick_look	ファイルをプレビュー	path

例

// Get selected files in Finder
What files do I currently have selected in Finder?

// Search for files
Find all PDF files in my Documents folder

// Preview a file
Show me a preview of ~/Documents/report.pdf

通知

注意：通知を送信するには、「システム設定」>「通知」>「スクリプトエディタ」で通知を有効にする必要があります。

コマンド	説明	パラメーター
send_notification	通知を表示	title、message、sound（省略可）
toggle_do_not_disturb	おやすみモードを切り替え	なし

例

// Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"

// Toggle Do Not Disturb
Turn on Do Not Disturb mode

システム

コマンド	説明	パラメーター
volume	システム音量を設定	level（0～100）
get_frontmost_app	アクティブなアプリを取得	なし
launch_app	アプリケーションを開く	name
quit_app	アプリケーションを終了	name、force（省略可）
toggle_dark_mode	ダークモードを切り替え	なし

例

// Set system volume
Set my Mac's volume to 50%

// Get active application
What app am I currently using?

// Launch an application
Open Safari

// Quit an application
Close Spotify

// Toggle dark mode
Switch to dark mode

iTerm

コマンド	説明	パラメーター
paste_clipboard	iTerm に貼り付ける	なし
run	コマンドを実行	command、newWindow（省略可）

例

// Paste clipboard to iTerm
Paste my clipboard contents into iTerm

// Run a command in iTerm
Run "ls -la" in iTerm

// Run a command in a new iTerm window
Run "top" in a new iTerm window

ショートカット

コマンド	説明	パラメーター
run_shortcut	ショートカットを実行します	name、input（省略可）
list_shortcuts	利用可能なすべてのショートカットを一覧表示します	limit（省略可）

例

// List available shortcuts
List all my available shortcuts

// List with limit
Show me my top 5 shortcuts

// Run a shortcut
Run my "Daily Note in Bear" shortcut

// Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"

メール

コマンド	説明	パラメーター
create_email	Mail.appで新しいメールを作成します	recipient、subject、body
list_emails	メールボックスのメールを一覧表示します	mailbox（省略可）、count（省略可）、unreadOnly（省略可）
get_email	検索条件を指定して特定のメールを取得します	subject（省略可）、sender（省略可）、dateReceived（省略可）、mailbox（省略可）、account（省略可）、unreadOnly（省略可）、includeBody（省略可）

例

// Create a new email
Compose an email to [email protected] with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"

// List emails
Show me my 10 most recent unread emails

// Get a specific email
Find the email from [email protected] about "Project Update"

メッセージ

コマンド	説明	パラメーター
list_chats	利用可能なiMessageおよびSMSのチャットを一覧表示します	includeParticipantDetails（省略可、デフォルト：false）
get_messages	Messagesアプリからメッセージを取得します	limit（省略可、デフォルト：100）
search_messages	特定のテキストを含むメッセージを検索します	searchText、sender（省略可）、chatId（省略可）、limit（省略可、デフォルト：50）、daysBack（省略可、デフォルト：30）
compose_message	メッセージを入力済みの状態でMessagesアプリを開くか、自動送信します	recipient（必須）、body（省略可）、auto（省略可、デフォルト：false）

例

// List available chats
Show me my recent message conversations

// Get recent messages
Show me my last 20 messages

// Search messages
Find messages containing "dinner plans" from John in the last week

// Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"

メモ

コマンド	説明	パラメーター
create	Markdown風の書式でメモを作成します	title、content、format（書式オプション付きで省略可）
createRawHtml	HTMLコンテンツを直接指定してメモを作成します	title、html
list	メモを一覧表示します。特定のフォルダーを指定できます	folder（省略可）
get	タイトルを指定して特定のメモを取得します	title、folder（省略可）
search	特定のテキストを含むメモを検索します	query、folder（省略可）、limit（省略可、デフォルト：5）、includeBody（省略可、デフォルト：true）

例

// Create a new note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists

// Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"

// List notes
Show me all my notes in the "Work" folder

// Get a specific note
Show me my note titled "Shopping List"

// Search notes
Find notes containing "recipe" in my "Cooking" folder

Pages

コマンド	説明	パラメーター
create_document	プレーンテキストで新しいPages書類を作成します	content

例

// Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."

アーキテクチャ

applescript-mcpサーバーはTypeScriptで構築されており、モジュール式アーキテクチャに従っています。

コアコンポーネント

1. AppleScriptFramework（framework.ts）：次の機能を備えたメインのサーバークラスです。

   • MCP プロトコル通信を管理します
   • ツールの登録と実行を処理します
   • ログ機能を提供します
   • AppleScript コマンドを実行します

2. カテゴリ（src/categories/*.ts）：機能別に整理されたモジュール式のスクリプトコレクションです。

   • 各カテゴリには、関連するスクリプトが含まれます（例：カレンダー、システム、メモ）
   • カテゴリは index.ts でフレームワークに登録されます

3. 型（src/types/index.ts）：次を定義する TypeScript インターフェースです。

   • ScriptDefinition：個々のスクリプトの構造
   • ScriptCategory：関連するスクリプトのコレクション
   • LogLevel：標準のログレベル
   • FrameworkOptions：設定オプション

実行フロー

1. クライアントが MCP プロトコル経由でツールリクエストを送信します
2. サーバーが適切なカテゴリとスクリプトを特定します
3. スクリプトの内容が生成されます（静的、または関数による動的生成）
4. macOS の osascript コマンド経由で AppleScript が実行されます
5. 結果がクライアントに返されます

ログシステム

このフレームワークには、次の機能を備えた包括的なログシステムがあります。

• stderr と MCP ロギングプロトコルの両方にログを出力します
• 複数の重大度レベル（debug、info、warning、error など）に対応します
• トラブルシューティングに役立つ詳細な実行情報を提供します

開発

セットアップ

# Install dependencies
npm install

# Build the server
npm run build

# Launch MCP Inspector
# See: https://modelcontextprotocol.io/docs/tools/inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

新しい機能の追加

1. カテゴリファイルを作成する

src/categories/newcategory.ts を作成します。

import { ScriptCategory } from "../types/index.js";

export const newCategory: ScriptCategory = {
  name: "category_name",
  description: "Category description",
  scripts: [
    // Scripts will go here
  ],
};

2. スクリプトを追加する

{
  name: "script_name",
  description: "What the script does",
  schema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        description: "Parameter description"
      }
    },
    required: ["paramName"]
  },
  script: (args) => `
    tell application "App"
      // AppleScript code using ${args.paramName}
    end tell
  `
}

3. カテゴリを登録する

src/index.ts を更新します。

import { newCategory } from "./categories/newcategory.js";
// ...
server.addCategory(newCategory);

高度なスクリプト開発

より複雑なスクリプトでは、次のことができます。

1. 動的なスクリプト生成を使用する：

   script: (args) => {
     // Process arguments and build script dynamically
     let scriptContent = `tell application "App"\n`;
     
     if (args.condition) {
       scriptContent += `  // Conditional logic\n`;
     }
     
     scriptContent += `end tell`;
     return scriptContent;
   }
   

2. 複雑なデータを処理する：

   // Example from Notes category
   function generateNoteHtml(args: any): string {
     // Process markdown-like syntax into HTML
     let processedContent = content;
     
     if (format.headings) {
       processedContent = processedContent.replace(/^# (.+)$/gm, '<h1>$1</h1>');
       // ...
     }
     
     return processedContent;
   }
   

デバッグ

MCP Inspector の使用

MCP Inspector は、サーバーのテストとデバッグに使えるウェブインターフェースを提供します。

npm run inspector

ログ記録

環境変数を設定して、デバッグログを有効にします。

DEBUG=applescript-mcp* npm start

設定例

npm run build の実行後、次の内容を mcp.json ファイルに追加します。

{
  "mcpServers": {
    "applescript-mcp-server": {
      "command": "node",
      "args": ["/path/to/applescript-mcp/dist/index.js"]
    }
  }
}

よくある問題

• 権限エラー：システム設定 > セキュリティとプライバシー > プライバシー > オートメーションを確認してください
• スクリプトの失敗：統合する前に、Script Editor.app でスクリプトを直接テストしてください
• 通信の問題：stdio ストリームがリダイレクトされていないことを確認してください
• データベースへのアクセス：一部の機能（Messages など）には、フルディスクアクセスの許可が必要です

リソース

• AppleScript 言語ガイド
• MCP プロトコルのドキュメント
• 課題トラッカー

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

MIT ライセンスの詳細については、LICENSE を参照してください