omnifocus-mcp

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

macOS のみ対応。 同じマシンで OmniFocus が実行されている必要があります。実装全体は osascript -l JavaScript を介して OmniFocus 内で OmniJS スニペットを実行します — AppleScript の文字列生成は行わず、スクリプティング辞書の制限もありません。

前提条件

• macOS (Omni Automation は macOS 専用です。他のプラットフォームではサーバーは起動しません)

• OmniFocus がインストールされ、実行中であること

• Node.js ≥ 20

Related MCP server: OmniFocus MCP Server

インストール

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

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"]
    }
  }
}

利用可能なツール

読み取り

書き込み

アドレス指定モデル

このサーバーが返すすべてのエンティティには、安定した 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 呼び出し — Application('OmniFocus').evaluateJavascript() — を行い、すべてのロジックを OmniFocus 内で OmniJS (Omni Automation) として実行します。これにより、より制限されたスクリプティング辞書ではなく、Omni Automation API の全機能 (繰り返しルール、レビュー間隔、パースペクティブ、予測、添付ファイル、URL オートメーションなど) にアクセスできます。

引数の注入。 代替手段は文字列補間で osascript コマンドを構築するため、名前内のアポストロフィ、引用符、バックスラッシュ、ユニコードで壊れる可能性があります。このサーバーはすべての引数を JSON.stringify で JS リテラルにシリアライズします。

エンティティのアドレス指定。 代替手段は主に名前でエンティティを指定します。このサーバーはすべてのエンティティに対して安定した id (id.primaryKey) を返し、名前を ID 候補にマッピングする resolve_name を提供します — 名前が曖昧な場合に黙って 1 つを選択するのではなく、完全なパス付きですべての一致を返します。

完全な CRUD。 このサーバーは、タスク・プロジェクト・フォルダ・タグの作成、編集、完了、ドロップ、削除、移動をサポートします — さらに繰り返しルールと OmniFocus 4 の planned date にも対応。

開発

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

テスト

ユニットテスト (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 のみ)

• 変更は焦点を絞ってください — PR ごとに 1 つの機能または修正

アーキテクチャ概要

サーバーは osascript -l JavaScript を介して OmniFocus 内で OmniJS スニペットを実行します。各ツールには 3 つの層があります:

• スキーマ (src/schemas/shapes.ts) — 入力検証と出力解析のための Zod スキーマ

• スニペット (src/snippets/*.js) — OmniFocus 内で実行される OmniJS コード。プレーンな ES5 JavaScript (インポートなし、TypeScript なし)。引数は __ARGS__ プレースホルダーを介して注入されます。

• ツールハンドラー (src/tools/*.ts) — 入力を検証し、runSnippet() を呼び出し、