OmniFocus

omnifocus-mcp

LLM 呼び出し元に Omni Automation の JavaScript API 全体を公開する MCP サーバーです。

macOS 専用です。 同じマシンで OmniFocus が起動している必要があります。実装全体は osascript -l JavaScript を介して OmniFocus 内で OmniJS スニペットを実行します。AppleScript の文字列生成やスクリプティング辞書の制限はありません。

前提条件

• macOS（Omni Automation は macOS 専用です。このサーバーはほかのプラットフォームでは起動しません）
• OmniFocus がインストールされ、起動していること
• Node.js ≥ 20

インストール

このパッケージは @scardis/omnifocus-mcp として npm に公開されています。

npx を使用する場合（インストール不要）

MCP クライアントの設定に追加します（例：Claude Desktop の claude_desktop_config.json）。

{
  "mcpServers": {
    "omnifocus": {
      "command": "npx",
      "args": ["-y", "@scardis/omnifocus-mcp"]
    }
  }
}

ソースからインストールする場合

git clone https://github.com/steveardis/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

続いて、MCP クライアントを設定します。

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

利用可能なツール

読み取り

ツール	説明
list_projects	ステータス、folderId、フラグによる任意のフィルタリングに対応したプロジェクト一覧です。デフォルトでは完了済み／中止済みの項目を除外します。上限（デフォルトは 100 件）。
get_project	安定した ID でプロジェクトの詳細をすべて取得します
list_tasks	projectId、folderId、inbox: true、または all: true で対象を指定し、ステータス／タグ／期限／フラグによる任意のフィルタリングに対応したタスク一覧です。上限（デフォルトは 200 件）。
get_task	安定した ID でタスクの詳細をすべて取得します。延期日／予定日／期限、タグ、繰り返しルール、parentTaskId を含みます
list_folders	ステータスによる任意のフィルタリングに対応したフォルダー一覧です。上限（デフォルトは 200 件）。
get_folder	安定した ID でフォルダーの詳細をすべて取得します。子フォルダーとプロジェクトの ID を含みます
list_tags	ステータスによる任意のフィルタリングに対応したタグ一覧です。上限（デフォルトは 200 件）。
get_tag	安定した ID でタグの詳細をすべて取得します。子タグの ID を含みます
resolve_name	名前から安定した ID の候補を解決します。あいまいな候補を黙って選ぶことはありません。すべての一致候補を返します

書き込み

ツール	説明
create_task	インボックス、プロジェクト、またはサブタスクとしてタスクを作成します。延期日／予定日／期限、タグ、フラグ、見積もり時間（分）、繰り返しルールに対応しています。
edit_task	タスクの任意のフィールドを編集します。日付または繰り返しをクリアするには null を渡します。省略したフィールドは変更されません。
complete_task	タスクを完了としてマークします
drop_task	タスクを中止としてマークします
delete_task	タスクとすべてのサブタスクを完全に削除します
create_project	プロジェクトを作成します。フォルダーへの配置は任意です。タイプ、ステータス、レビュー間隔、タグに対応しています。
edit_project	プロジェクトのフィールドを編集します
complete_project	プロジェクトを完了としてマークします
drop_project	プロジェクトを中止としてマークします
delete_project	プロジェクトとすべてのタスクを完全に削除します
create_folder	フォルダーを作成します。別のフォルダー内への作成も可能です
edit_folder	フォルダーの名前を変更します
delete_folder	フォルダーとその配下全体を完全に削除します
create_tag	タグを作成します。別のタグ内への作成も可能です
edit_tag	タグ名またはステータスを編集します
delete_tag	タグと子タグを完全に削除します
move_task	タスクをプロジェクトに移動するか、別のタスクのサブタスクにします
move_project	プロジェクトをフォルダーまたはトップレベルに移動します

ID による指定

このサーバーが返すすべてのエンティティには、安定した id フィールド（OmniFocus の id.primaryKey）が含まれています。以降の呼び出しでは、名前ではなくこの ID を使用してください。名前はあいまいになることがありますが、ID は一意です。

名前は分かっていて ID が分からない場合は、resolve_name を使用してください。候補の一覧が返されます。複数の候補が返された場合は、path フィールドを確認し、書き込み操作に進む前にユーザーに候補の選択を求めてください。

他のOmniFocus MCPサーバーとの比較

注目すべき代替ツールとして、次の2つがあります。 themotionmachine/OmniFocus-MCPと jqlts1/omnifocus-mcp-enhanced（上記をフォークし、ツールを追加したもの）です。

スクリプティングAPI。 代替ツールはJXAスクリプティング辞書またはAppleScriptを使ってOmniFocusを操作します。このサーバーは、JXAを1回呼び出すだけであるApplication('OmniFocus').evaluateJavascript()、すべてのロジックをOmniFocus内でOmniJS（Omni Automation）として実行します。これにより、より限定的なスクリプティング辞書ではなく、Omni Automation APIの全機能（繰り返しルール、レビュー間隔、パースペクティブ、予測、添付ファイル、URL自動化など）を利用できます。

引数の挿入。 代替ツールは文字列補間でosascriptコマンドを組み立てるため、名前にアポストロフィ、引用符、バックスラッシュ、Unicode文字が含まれると問題が起きることがあります。このサーバーは、すべての引数をJSON.stringifyでJSリテラルにシリアライズします。

エンティティの指定。 代替ツールは主に名前でエンティティを指定します。このサーバーは、すべてのエンティティに安定したid（id.primaryKey）を返し、名前をID候補に対応付けるresolve_nameを提供します。名前が曖昧な場合に黙って1つを選ぶのではなく、すべての一致候補を完全なパスとともに返します。

完全なCRUD。 このサーバーは、タスク、プロジェクト、フォルダ、タグの作成、編集、完了、破棄、削除、移動に対応しています。さらに、繰り返しルールとOmniFocus 4の予定日にも対応しています。

開発

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build (compiles TypeScript and copies snippets into dist/)
npm run build

新しいバージョンの公開手順はRELEASING.mdに記載されています。

テスト

単体テスト（OmniFocusは不要）

npm test

統合テスト

⚠️ 統合テストは実際のOmniFocusデータベースに対して実行されます。

テストの実行ごとに、__MCP_TEST_<uuid>__という名前の一時的な最上位フォルダを作成し、後処理時に削除します。後処理の前にテストが中断された場合は、クリーンアップスクリプトを実行してください。

npm run test:cleanup-fixtures

⚠️ 同期に関する警告： デフォルトでは、テスト用データが他のデバイスに伝播するのを防ぐため、OmniFocusの同期が有効になっている場合、統合テストは実行されません。先にOmniFocusの同期を無効にするか、MCP_TEST_ALLOW_SYNC=1を設定して許可してください（テスト用データは同期されます）。

# Default (refuses if sync enabled)
npm run test:integration

# With sync enabled (use carefully)
MCP_TEST_ALLOW_SYNC=1 npm run test:integration

古いテスト用データのクリーンアップ

npm run test:cleanup-fixtures

これにより、中断されたテストの実行後にOmniFocusに残った__MCP_TEST_*__フォルダと、孤立した__mcp_*__プロジェクト／タグが削除されます。

コントリビューション

コントリビューションを歓迎します。始めるには、次の手順に従ってください。

1. フォークしてクローンします
2. 依存関係をインストールします： npm install
3. 単体テストを実行します（OmniFocusは不要）：npm test
4. 統合テストを実行します（macOS + OmniFocusが必要）：npm run test:integration

PRを提出する前に

• npm run typecheck — エラーなしで成功すること
• npm test — すべての単体テストが成功すること
• npm run test:integration — すべての統合テストが成功すること（macOSのみ）
• 変更の範囲を絞ること — 1つのPRにつき、機能または修正は1つ

アーキテクチャの概要

サーバーは、osascript -l JavaScriptを通じてOmniFocus内でOmniJSスニペットを実行します。各ツールは次の3つのレイヤーで構成されています。

• スキーマ（src/schemas/shapes.ts）— 入力検証と出力解析のためのZodスキーマ
• スニペット（src/snippets/*.js）— OmniFocus内で実行されるOmniJSコード。プレーンなES5 JavaScriptです（importやTypeScriptは使用しません）。引数は__ARGS__プレースホルダーを通じて挿入されます。
• ツールハンドラー（src/tools/*.ts）— 入力を検証し、runSnippet()を呼び出して、結果を解析します

新しいツールを追加する場合：

1. src/schemas/shapes.tsで入出力スキーマを定義し、src/schemas/index.tsからエクスポートします
2. src/snippets/にOmniJSスニペットを作成します
3. src/runtime/snippetLoader.tsのALLOWED_SNIPPETSにスニペット名を追加します
4. src/tools/にツールハンドラーを作成し、src/tools/index.tsに登録します
5. スキーマの単体テストと、OmniFocusに対して実行する統合テストを追加します

OmniJS スニペットの作成

スニペットは Node.js ではなく、OmniFocus の JavaScript ランタイム内で実行されます。主な制約は次のとおりです。

• ES5 形式の JavaScript — var と function(){} を使用します。古い OmniFocus のバージョンではアロー関数を使用しないでください
• インポート不可 — flattenedTasks、flattenedProjects、moveTasks などの OmniJS グローバルは、すべて直接使用できます
• JSON を返す — 常に return JSON.stringify({ ok: true, data: ... }) を返してください
• エラーパターン — 名前付きエラー（NotFoundError、ValidationError）をスローすると、ブリッジが捕捉してラップします

ライセンス

MIT