OmniFocus MCP Plus

A comprehensive MCP server for OmniFocus 4 with 34 tools covering task management, project/folder/tag CRUD, custom perspectives, 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 (34)

Task Management

Task Queries

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

The server uses two execution patterns:

• AppleScript (original tools) — task creation, editing, removal via osascript
• OmniJS via JXA (v0.2.0+ tools) — inline JavaScript executed inside OmniFocus via runOmniJs(). No AppleScript escaping issues, native access to appendStringToNote(), markIncomplete(), Task.RepetitionRule, folder/tag CRUD, etc.

Changelog

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

• JSON injection in AppleScript return strings — Task names containing " or \ may produce malformed JSON from AppleScript-based tools. OmniJS-based tools (v0.2.0+) are not affected.
• appleScriptDateCode ignores timezone offset — Works correctly when machine timezone matches the ISO string offset.
• Parameter injection in executeOmniFocusScript is fragile — Uses regex replacement. OmniJS-based tools use direct JSON injection instead.

Contributing

PRs welcome! The codebase has two patterns for adding tools:

1. OmniJS tools (preferred for new tools) — 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.
2. AppleScript tools (legacy) — used by the original tools. More fragile due to escaping but still works.

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