omnifocus-mcp

# omnifocus-mcp MCP server for OmniFocus — enables AI assistants to manage tasks, projects, tags, and run GTD weekly reviews via the Model Context Protocol. ## Requirements - macOS with OmniFocus installed - Node.js 18+ ## Setup ```bash npm install npm run build ``` Add to `.mcp.json` (project or `~/.claude/settings.json`): ```json { "mcpServers": { "omnifocus": { "command": "node", "args": ["/path/to/omnifocus-mcp/dist/index.js"] } } } ``` ## Tools (36 total) ### Inbox - **get_inbox_tasks** — List tasks from system, private, or work inbox (paginated, excludes completed by default) - **process_inbox_task** — Move task to project, assign tags/dates/flags - **quick_entry** — Create a new task in inbox or directly in a project ### Tasks - **get_task** — Fetch a single task by ID - **complete_task** — Mark task as completed - **uncomplete_task** — Reopen a completed task - **delete_task** — Delete a task - **update_task** — Modify name, note, tags, dates, flagged, completed status - **create_subtasks** — Break a task into subtasks - **search_tasks** — Search incomplete tasks by name ### Projects - **get_projects** — List projects filtered by status, optionally scoped to a folder - **get_project_by_name** — Look up a project ID by name - **get_project_tasks** — List tasks within a project (paginated) - **create_project** — Create project with optional folder, tags, review interval, and initial tasks - **update_project** — Change status, review interval, name, note - **convert_task_to_project** — Promote a task to a project, preserving name/note/tags ### Folders - **get_folders** — List folders (areas of responsibility) with active project counts and parent IDs - **create_folder** — Create a folder, optionally nested inside a parent - **update_folder** — Rename a folder - **move_project** — Move a project into a different folder - **delete_folder** — Delete a folder (refuses if it contains projects) ### Tags - **get_tags** — List tags (with limit) - **create_tag** — Create tag (supports nesting via parent tag ID) - **update_tag** — Rename a tag and/or reparent it (pass empty parentTagId to move to document root) - **delete_tag** — Delete a tag by ID (refuses if it has child tags; tasks are untagged, not deleted) ### Review - **get_projects_due_for_review** — Projects past their review date - **get_review_digest** — One row per project with stall / next-action (Planned) / deadline / last-activity signals; `scope=due` or `all-active`, optional `folderId`, `onlyStalled`, pagination — the engine for weekly review and the one-time backlog pass - **mark_project_reviewed** — Reset review timer - **batch_mark_reviewed** — Reset review timers for many projects in one call - **get_stale_tasks** — Tasks in a project not modified for N days - **get_overdue_tasks** — Tasks past due date - **get_forecast** — Tasks due in the next N days - **get_completed_tasks** — Tasks completed since a given date - **get_flagged_tasks** — List all flagged incomplete tasks (your "hot list") - **get_available_tasks** — List actionable tasks in a project (not blocked, not deferred) - **get_tasks_by_tag** — List incomplete tasks matching any of the given tags (e.g., @waiting_for, @errands); `sortByAge`/`minAgeDays` surface aging commitments with a `daysWaiting` field; `folderId` (optional) restricts to tasks whose project lives in a specific folder (area of responsibility), keeping work and personal commitment reviews separate — mirrors `get_review_digest`'s `folderId` ## Response shape Tool responses are returned as single-line JSON with unset/empty fields omitted to reduce token usage. Specifically: `null`, `undefined`, `""`, `[]`, and empty objects are stripped from response payloads. `false` and `0` are preserved (they carry real values). Consumers should treat absent keys as unset — for example, a task with no due date will have no `dueDate` key at all rather than `dueDate: null`. ## Development ```bash npm run dev # watch mode npm test # run tests npm run build # compile TypeScript ```