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

npm install
npm run build

Add to .mcp.json (project or ~/.claude/settings.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

npm run dev       # watch mode
npm test          # run tests
npm run build     # compile TypeScript