OmniFocus MCP Plus

A comprehensive MCP server for OmniFocus 4 with 41 tools covering task management, project/folder/tag CRUD, custom perspectives, notifications, and advanced filtering.

Originally forked from jqlts1/omnifocus-mcp-enhanced. Additional tools inspired by vitalyrodnenko/OmnifocusMCP.

Installation

Requires macOS with OmniFocus 4 and Node.js 18+.

From Source

git clone https://github.com/psufka/omnifocus-mcp-plus.git
cd omnifocus-mcp-plus
npm install && npm run build
npm test  # all tests should pass
claude mcp add omnifocus -- node "$(pwd)/dist/server.js"

Restart Claude Code to pick up the new server.

Tools (41)

Task Management

Task Queries

Notifications

Projects

Folders

Tags

Usage Examples

All tools are called automatically by Claude via MCP. The examples below show the tool parameters for common operations.

Tasks

Add a task with a due date and tags:

{
  "name": "Review quarterly report",
  "dueDate": "2026-03-15T17:00:00-05:00",
  "tags": ["Work", "Urgent"],
  "projectName": "Q1 Review"
}

Set a task to repeat every weekday:

{
  "task_id": "abc123",
  "rule_string": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
  "schedule_type": "regularly"
}

Set a task to repeat 3 days after completion:

{
  "task_id": "abc123",
  "rule_string": "FREQ=DAILY;INTERVAL=3",
  "schedule_type": "from_completion"
}

Append to a task's note (without overwriting):

{
  "object_type": "task",
  "object_id": "abc123",
  "text": "\nUpdated 2026-03-10: waiting on response"
}

Projects

List stalled projects (active but stuck):

{ "stalledOnly": true }

List projects in a folder sorted by remaining tasks:

{
  "folder": "Work",
  "status": "active",
  "sortBy": "remainingTaskCount",
  "sortOrder": "desc"
}

Folders & Tags

Create a nested folder:

{ "name": "Q2 Projects", "parent": "Work" }

Create a nested tag:

{ "name": "Urgent", "parent": "Priority" }

Put a tag on hold:

{ "name_or_id": "Waiting", "status": "on_hold" }

Filtering

Get overdue tasks in a specific project:

{
  "overdue": true,
  "projectFilter": "Home Renovation"
}

Get tasks due this week with a specific tag:

{
  "dueThisWeek": true,
  "tagFilter": "Work"
}

Date Format

All dates must use full ISO 8601 with timezone offset. Bare dates like 2026-03-15 resolve to UTC midnight and display as the wrong day in local time.

"2026-03-15T17:00:00-05:00"   (CDT)
"2026-03-15T17:00:00-06:00"   (CST)

RRULE Reference

The set_task_repetition tool uses iCal RRULE syntax:

Architecture

All tools use OmniJS via JXA — inline JavaScript executed inside OmniFocus via runOmniJs(). No AppleScript escaping issues, native access to all OmniJS APIs. Query tools use external .js scripts in src/utils/omnifocusScripts/ loaded via executeOmniFocusScript(). The core task/project CRUD tools (add, edit, remove) were migrated from AppleScript to OmniJS in v0.3.0.

Changelog

v0.3.1

• reorder_task (41 total) — move tasks before/after siblings or to beginning/ending of container

v0.3.0

• 6 new tools (40 total): list_subtasks, duplicate_task, batch_move_tasks, list_notifications, add_notification, remove_notification

• Tag AND filter — tagMatchMode: "all" on filter_tasks requires all specified tags

• Effective dates — effectiveDueDate/effectiveDeferDate in all query results (inherited from parent)

• AppleScript → OmniJS migration — addOmniFocusTask, addProject, editItem, removeItem rewritten. Fixes special character crashes, timezone issues, and enables task move

v0.2.2

• Fix OmniJS scripts ignoring parameters — forecastTasks, flaggedTasks, inboxTasks now read injectedArgs instead of hardcoding defaults

• Fix get_task_counts deferred count — counts future defer dates instead of blocked status

• Fix tag replacement iteration bug — reverse iteration prevents skipped elements

• Fix JSON escaping in AppleScript returns — task names with " or \ no longer break JSON

• Fix executeJXA temp file leak — cleanup now in finally block

• Remove unimplemented filter_tasks params — hasEstimate, estimateMin, estimateMax, hasNote, inInbox

• Raise perspective engine limits — 50/15 → 500/200

v0.2.0

• 17 new tools using OmniJS: append_to_note, uncomplete_task, set_task_repetition, list_projects, search_projects, get_project_counts, get_task_counts, folder CRUD (5 tools), tag CRUD (5 tools)

• New runOmniJs() helper — simplified inline OmniJS execution with JSON arg injection, no external script files needed

• Renamed from omnifocus-mcp-enhanced-fork to omnifocus-mcp-plus

v0.1.0

Fork of jqlts1/omnifocus-mcp-enhanced with:

• Fix task completion for inbox and repeating tasks

• Fix all due-date filters being silently ignored

• Fix dateFormatter discarding time components

• Fix multiline notes breaking AppleScript

• Fix JSON escaping in AppleScript return strings

• Fix single-quote escaping inserting unwanted backslashes

• Fix isDateInCurrentWeek using Monday-start weeks

• Display task IDs in all output tools

• Duplicate-name protection on removeItem

• Require full ISO 8601 dates with timezone

• Move task to project/parent/inbox support

• All Chinese comments translated to English

• Test suite wired up (8 unit tests via tsx)

Known Limitations

• Parameter injection in executeOmniFocusScript is fragile — Uses regex replacement for query scripts. CRUD tools use direct JSON injection via runOmniJs() instead.

• Notification API — Relative notification offset retrieval may not work on all OmniFocus versions. Absolute notifications are fully supported.

Contributing

PRs welcome! All tools use OmniJS — write inline JavaScript that runs inside OmniFocus via runOmniJs(). No escaping issues, full access to the OmniJS API. See src/tools/primitives/folderTools.ts for examples.

To add a new tool:

1. Create a primitive in src/tools/primitives/yourTool.ts

2. Create a definition in src/tools/definitions/yourTool.ts (Zod schema + handler)

3. Register in src/server.ts

4. npm run build && npm test

Credits

• jqlts1/omnifocus-mcp-enhanced — original MCP server with perspective support

• vitalyrodnenko/OmnifocusMCP — reference implementation for folder/tag CRUD, project listing, and OmniJS patterns

License

MIT