OmniFocus MCP サーバー

OmniFocus を Claude やその他の MCP 互換 AI アシスタントに接続する Model Context Protocol (MCP) サーバーです。

概要

このサーバーは、AI アシスタントと OmniFocus データベースを橋渡しします。自然な会話を通じて、アシスタントはタスクやプロジェクトの照会、作成、編集、削除（一括操作を含む）を行うことができます。できることの例:

• シラバス PDF を、タスク、タグ、延期日、期限日を備えた完全に仕様化されたプロジェクトに変換する

• 会議の文字起こしをアクションのリストに変換する

• タグ、プロジェクト、フォルダを会話形式で監査・再編成する

• タスク、プロジェクト、タグの可視化を作成する

• 一度のバッチ操作で数十件の項目を処理する

Related MCP server: MCP OmniFocus

クイックスタート

前提条件

• OmniFocus がインストールされた macOS

• Node.js 20 以降（npx を使用する場合）

サーバーが初めて OmniFocus と通信するとき、macOS が自動化アクセスを許可するか尋ねます。一度許可すれば準備完了です。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json にサーバーを追加します:

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

その後、Claude Desktop を再起動します。

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp

他の MCP クライアントも同様に動作します: stdio 経由で npx -y omnifocus-mcp を起動します。

会話の例

対象を絞ったクエリ:

「今週期限のフラグ付きタスクをすべて表示して」

「Work フォルダの次のアクションは何？」

「各プロジェクトのタスク数を数えて」

再編成:

「すべてのタスクにエネルギーレベルのタグを付けたい。タグがないタスクをすべてリストアップして、追加すべきタグの提案も見せて。適切だと思う変更は私が行うから。その後、OmniFocus で変更を実行して。」

どこからでもキャプチャ:

「法治の重要性についての詳しい説明をありがとう。私のアクティビズムプロジェクトに、毎週議員に電話するよう思い出させる繰り返しタスクを追加して。この会話の要約をメモ欄に含めて。」

パースペクティブの操作:

「利用可能なパースペクティブは何？」

「Inbox パースペクティブの中身を見せて」

文字起こしや PDF の処理:

「今日の会議の文字起こしを貼り付けます。分析して、私に割り当てられたアクション項目を OmniFocus にタスクとして作成してください。'Product Development' プロジェクトに入れて。」

ツール

サーバーは 12 個のツールを提供します。オプションのパラメータはマークされています。

query_omnifocus

タスク、プロジェクト、フォルダを対象を絞ったフィルタで照会します — データベース全体をダンプするよりはるかに高速で軽量です。完全なリファレンスは QUERY_TOOL_REFERENCE.md、実例は QUERY_TOOL_EXAMPLES.md を参照してください。

利用可能なフィルタ:

• コンテナ: projectName（大文字小文字を区別しない部分一致; "inbox" は受信トレイを対象）、projectId、folderId（サブフォルダを含む）、folderName（大文字小文字を区別しない部分一致、サブフォルダを含む）

• 名前: taskName（大文字小文字を区別しない部分一致）

• タグ: tags（完全一致、大文字小文字を区別）

• ステータス: status — タスク: Next、Available、Blocked、DueSoon、Overdue、Completed、Dropped; プロジェクト: Active、OnHold、Done、Dropped

• 日付（未来志向）: dueWithin、deferredUntil、plannedWithin（範囲）、dueOn、deferOn、plannedOn（特定の日）。日数、"today"、"tomorrow"、"this week"、"next week"、または ISO 日付を受け付けます

• 日付（過去志向）: addedWithin、addedOn、completedWithin、completedOn、droppedWithin、droppedOn（完了/ドロップフィルタには includeCompleted: true が必要）

• フラグとその他: flagged、inbox、hasNote、isRepeating、reviewDue（プロジェクトのみ）

dump_database

データベースの完全な状態を取得します。包括的な分析に使用します。対象を絞ったものには query_omnifocus を優先してください。

• hideCompleted (オプション): 完了/ドロップ済みタスクを非表示（デフォルト: true）

• hideRecurringDuplicates (オプション): 繰り返しタスクの重複インスタンスを非表示（デフォルト: true）

add_omnifocus_task

新しいタスクを作成します。

• name

• projectName (オプション): タスクを追加するプロジェクト（デフォルトは受信トレイ）

• parentTaskId / parentTaskName (オプション): 既存のタスクの下にネスト

• note、dueDate、deferDate、plannedDate、flagged、estimatedMinutes、tags (すべてオプション)

• repeat (オプション): 繰り返しにする — 繰り返し項目 を参照

add_project

新しいプロジェクトを作成します。

• name

• folderName (オプション): プロジェクトを配置するフォルダ

• sequential (オプション): タスクを順番に完了する必要があるか

• note、dueDate、deferDate、flagged、estimatedMinutes、tags、repeat (すべてオプション)

edit_item

既存のタスクまたはプロジェクトを編集します。項目を移動する方法でもあります — newProjectName を設定してタスクをプロジェクトに移動するか、""/"inbox" に設定して受信トレイに送信します。

• id または name: 編集する項目（id が優先）

• itemType: task または project

• 共通: newName、newNote、newDueDate、newDeferDate、newFlagged、newEstimatedMinutes（日付は ISO 形式; 空文字列でクリア）

• タスク: newStatus（incomplete、completed、dropped、skipped — skipped は繰り返しタスクのみ）、addTags、removeTags、replaceTags、newProjectName、newPlannedDate

• プロジェクト: newProjectStatus（active、completed、dropped、onHold）、newFolderName、newSequential、markReviewed（プロジェクトのレビュー間隔に基づいて次のレビュー日を設定）

• 繰り返し: newRepeat で新しいルールを設定（作成時の repeat と同じ形式）; newRepeat: null でクリア

remove_item

タスクまたはプロジェクトを削除します。

• id または name: 削除する項目

• itemType: task または project

batch_add_items

1 回の操作で複数のタスクとプロジェクトを作成します。各項目は add_omnifocus_task / add_project と同じフィールドに加えて、type（task または project）とオプションの階層ヘルパーを受け付けます:

• tempId: 同じバッチ内の他の項目が参照できる一時 ID

• parentTempId: この項目を別のバッチ項目の tempId の下にネスト

{
  "items": [
    { "type": "project", "name": "My Project", "tempId": "proj1" },
    { "type": "task", "name": "First task", "parentTempId": "proj1" },
    { "type": "task", "name": "Parent task", "parentTempId": "proj1", "tempId": "t1" },
    { "type": "task", "name": "Subtask", "parentTempId": "t1" }
  ]
}

batch_remove_items

1 回の操作で複数のタスクまたはプロジェクトを削除します。各項目は id または name に加えて itemType を取ります。

list_perspectives

利用可能なパースペクティブを一覧表示します。組み込みとカスタムの両方（カスタムパースペクティブは OmniFocus Pro の機能です）。

• includeBuiltIn、includeCustom (オプション、デフォルト: true)

get_perspective_view

指定したパースペクティブに表示される項目を取得します。

• perspectiveName: 例: Inbox、Flagged、またはカスタムパースペクティブ名

• limit (オプション、デフォルト: 100)、includeMetadata (オプション)、fields (オプション)

list_tags

すべてのタグを、階層、アクティブ状態、タスク数とともに一覧表示します。

• includeDropped (オプション、デフォルト: false)

create_tag

タグを作成します。オプションで既存の親の下にネストできます。

• name

• parentTagName / parentTagID (オプション; ID が優先)

繰り返し項目

add_omnifocus_task、add_project、および batch_add_items の各項目は repeat オブジェクトを受け付けます。edit_item は newRepeat を受け付けます。スケジュールを記述すると、サーバーが ICS 繰り返しルールをコンパイルするため、RRULE を手書きする必要はありません。

{ "name": "Weekly review", "repeat": { "method": "start-after-completion", "unit": "week" } }
{ "name": "Strength work", "repeat": { "method": "fixed", "unit": "week", "weekdays": ["TU","TH"] } }

method は意図的に選んでください — 手動で最も間違えやすいフィールドです。fixed の場合、最後の発生が完了していなくてもスケジュールどおりに発生するため、逃した週は backlog が残ります。start-after-completion の場合、次の発生は実際に完了した時点からスケジュールされるため、習慣は単に再開されます。

ルールを読み戻すには、query_omnifocus で repetitionRule（ICS 文字列）と repetitionMethod フィールドを使用するか、isRepeating でフィルタします。

現在サポートされていないもの: 位置指定の月次ルール（「第 3 火曜日」）、特定の月日、終了条件（COUNT/UNTIL）。これらは OmniFocus で直接設定してください。

リソース

リソースを使用すると、MCP クライアントはツール呼び出しなしで OmniFocus データを会話のコンテキストとして添付できます。Claude Code では @ と入力して参照できます。Claude Desktop やその他のリソース対応クライアントは直接添付できます。すべてのリソースは JSON を返します。

2 つのテンプレートリソースは、利用可能なすべての値の一覧表示と {name} パラメータのオートコンプリートをサポートしています。

サーバー指示とロギング

指示: MCP ハンドシェイク中に、サーバーは使用ガイダンスをクライアントに送信します — ツール選択のアドバイス（dump_database より query_omnifocus を優先）、フィルタのヒント、リソースカタログ。設定は不要です。

ロギング: サーバーは MCP ロギングプロトコルを介して構造化ログを出力します。クライアントは logging/setLevel（debug、info、warning、error など）で詳細度を調整できます。スクリプト実行のタイミングとエラーは自動的にログに記録されます。

仕組み

サーバーは osascript を通じて OmniFocus と通信し、適切な箇所では JXA（JavaScript for Automation）と OmniFocus に組み込まれた Omni Automation（OmniJS）を使用します。公式の MCP TypeScript SDK 上に構築されており、stdio 経由でクライアントと通信します。

共有デーモン

omnifocus-mcp を起動すると、共有バックグラウンドデーモンに接続する小さなシムが起動し、まだ起動していなければデーモンを1つ起動します。マシン上の各クライアントはそれぞれ独立した MCP セッションを取得しますが、すべてその単一プロセス内で実行されます。

これは、複数のエージェントが同時に OmniFocus を使用する場合に重要です。OmniFocus は AppleEvents によって駆動されるシングルスレッドのアプリケーションであり、サーバーは同時に実行する osascript 呼び出しの数を制限します。各クライアントが独自のサーバーを実行していたとき、その上限はプロセスごとでした。つまり、10クライアントがあれば、1つのアプリに対して10の独立した予算が設定され、AppleEvent のタイムアウトが発生していました。1つのプロセスを共有することで、その上限はグローバルになります。

デーモンは 0700 ディレクトリ（デフォルトでは ~/.omnifocus-mcp/daemon-<version>.sock）内の Unix ドメインソケットで待ち受けするため、アクセスはファイルシステムによって強制されます。ネットワークポートもトークンもありません。アイドル期間中にクライアントの接続がなくなると自動的に終了し、ソケットの隣にある daemon.log にログを記録します。

ソケット名にはパッケージバージョンが含まれているため、アップグレードしても以前のバージョンのデーモンと通信してしまうことは決してありません。アップグレード直後には一時的に2つのデーモンが見えることがあります。古いデーモンはすでに接続しているクライアントへのサービスを継続し、最後のクライアントが切断すると終了します。古いデーモンにまだ接続しているクライアントには、帯域内でそのことが通知されます。新しいデーモンが稼働している間、すべてのツール結果には1行のアップグレード通知が含まれるため、誰も再接続を覚えておく必要はありません。

クライアント設定に関しては何も変わりません。デーモンを起動できない場合（特殊なサンドボックス、読み取り専用のホームディレクトリなど）、シムは以前のバージョンとまったく同様に、プロセス内でスタンドアロンサーバーを実行するフォールバックを行います。

環境変数

ロードマップ

• MCP prompt サポート

• プロジェクトとタスクの通知の操作

• 機能リクエストと既知の問題については GitHub issues を参照してください

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。CI はすべての PR で型チェック、単体テスト、ビルドを実行します。

npm install
npm test            # unit tests
npm run build       # compile to dist/
npm run test:integration  # requires OmniFocus; creates and removes TEST:-prefixed items

ライセンス

MIT