OmniFocus MCP

MCP server that gives AI assistants full control over OmniFocus on macOS.

45 tools, 3 resources, and 4 prompts covering tasks, projects, tags, folders, perspectives, forecast, notifications, and review workflows — all through the Model Context Protocol.

This project is not affiliated with, endorsed by, or associated with The Omni Group or OmniFocus. OmniFocus is a trademark of The Omni Group. This is an independent, non-commercial open-source project.

Quick Start

Install via Homebrew (if you don't have Homebrew, see the Homebrew installation guide):

brew tap vitalyrodnenko/omnifocus-mcp
brew install omnifocus-mcp

Then add to your MCP client config (Claude Desktop, Cursor, etc.):

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

That's it. The AI assistant now has full OmniFocus access.

What It Can Do

Tasks (23 tools)

Full lifecycle management for OmniFocus tasks:

• CRUD — create, get, update, delete individual tasks
• Batch operations — create, move, or delete multiple tasks in a single call
• Subtasks — create and list subtasks under any parent task
• Completion — mark complete, mark incomplete (supports repeating tasks)
• Search — full-text search across task names and notes with all filters applied
• Move and reparent — relocate tasks between projects, reparent tasks under other tasks, or move subtasks back to inbox/project without delete/recreate
• Duplicate — clone a task with all properties and optional subtasks
• Notifications — list, add, and remove notifications (absolute date or relative offset)
• Repetition — set or clear repetition rules with schedule type (regularly/after completion)
• Notes — append text to task notes without overwriting
• Safety model — destructive delete confirmations stay separate from non-destructive move/update workflows
• Aggregate counts — fast "how many" queries without listing individual tasks

Advanced Filtering

list_tasks and search_tasks support powerful filter combinations:

| Filter | Description | | --- | --- | | project | Scope to a single project by name | | tag / tags | Filter by one tag or multiple tags | | tagFilterMode | "any" (default) or "all" for multi-tag filtering | | flagged | Flagged tasks only | | status | "available", "remaining", "completed", "dropped", "all" | | dueBefore / dueAfter | Due date range (ISO 8601) | | deferBefore / deferAfter | Defer date range (ISO 8601) | | completedBefore / completedAfter | Completion date range (ISO 8601) | | addedBefore / addedAfter | Creation date range (ISO 8601) | | changedBefore / changedAfter | Last-modified date range (ISO 8601, maps to OmniFocus modified) | | plannedBefore / plannedAfter | Planned date range (ISO 8601) | | maxEstimatedMinutes | Tasks with estimated duration up to N minutes |

Sorting

All list/search tools support sortBy and sortOrder:

• Sort by: name, dueDate, deferDate, completionDate, estimatedMinutes, project, flagged, addedDate, changedDate, plannedDate
• Aliases: added -> addedDate, modified -> changedDate, planned -> plannedDate
• Sort order: asc (default) or desc
• Task payloads include addedDate and changedDate (ISO 8601 or null)

Projects (11 tools)

• CRUD — create, get, update, delete projects
• Lifecycle — complete, uncomplete, set status (active/on-hold/dropped)
• Organization — move between folders, search by name
• Filtering — by folder, status, completion date range, stalled-only flag
• Sorting — by name, due date, or other fields
• Aggregate counts — project counts by status, optionally scoped to a folder

Project Lifecycle Semantics

• Use complete_project when work is finished/closed (done/completed).
• Use set_project_status for organizational state only:
  • active = current
  • on_hold = paused (UI wording is often "on hold"/"on-hold")
  • dropped = intentionally abandoned/cancelled, not completed
• Use uncomplete_project to reopen a completed project back to active.
• In user-facing summaries, present business meaning first (project name, folder, and status transition), and include opaque IDs only as secondary references.

Tags (5 tools)

• CRUD — create, update (name and status), delete
• List — with status filter (active/on-hold/dropped/all), sorting, and limits
• Search — fuzzy name matching

Folders (5 tools)

• CRUD — create, get (with child projects and subfolders), update, delete
• Hierarchy — create nested folders with parent parameter
• List — all folders with limits

Forecast (1 tool)

• Structured view with sections: overdue, due today, flagged, deferred, and due this week

Perspectives (1 tool)

• List all available OmniFocus perspectives

Resources (3)

Live snapshots available to MCP clients:

| Resource | Description | | --- | --- | | Inbox | Current inbox tasks | | Today | Today's forecast (overdue + due today + flagged) | | Active Projects | All active projects with task counts |

Prompts (4)

Ready-to-use review workflows:

| Prompt | Description | | --- | --- | | Daily Review | Due-soon, overdue, and flagged tasks for daily planning | | Weekly Review | Active projects and next-action coverage analysis | | Inbox Processing | One-by-one inbox clarification decisions | | Project Planning | Guided planning for a specific project |

Implementations

Three implementations with identical tool names, parameters, and response shapes:

| Implementation | Language | Install | Recommended For | | --- | --- | --- | --- | | Rust | Rust | Homebrew (recommended) or source | Production use — single binary, fast startup | | Python | Python 3.11+ | uv from source | Local development, easy scripting | | TypeScript | Node.js 20+ | npm from source | Node.js ecosystems |

Detailed setup guides: Rust · Python · TypeScript

How It Works

The server runs JXA (JavaScript for Automation) scripts through macOS osascript. Each script uses the OmniFocus evaluateJavascript bridge to execute Omni Automation JavaScript inside OmniFocus itself, where full APIs like flattenedTasks, Task.Status, and new Task() are available. Data is serialized as JSON and returned through the MCP protocol with consistent schemas across all three implementations.

MCP Client Config Examples

Claude Desktop

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

Cursor

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

Python (source build)

{
  "mcpServers": {
    "omnifocus": {
      "command": "uv",
      "args": ["run", "omnifocus-mcp"]
    }
  }
}

TypeScript (source build)

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/OmnifocusMCP/typescript"
    }
  }
}

Keep only one OmniFocus MCP server enabled at a time to avoid duplicate tool surfaces.

Compatibility snippet:

{
  "mcpServers": {
    "omnifocus": {
      "command": "python",
      "args": ["-m", "omnifocus_mcp"]
    }
  }
}

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/OmnifocusMCP/typescript"
    }
  }
}

Switching Implementations

Switching Between Rust, Python, and TypeScript

• Use Rust when you want a single prebuilt omnifocus-mcp binary.
• Use Python when you want uv or python -m execution and fast local iteration.
• Use TypeScript when you want node execution from typescript/dist/index.js.
• Restart the MCP client so it reloads the server command after you switch implementations.

Prerequisites

• macOS (required — OmniFocus is macOS-only)
• OmniFocus installed and running
• Automation permission granted to the terminal/editor (System Settings → Privacy & Security → Automation)

For source builds only:

• Python 3.11+ and uv (Python implementation)
• Node.js 20+ and npm (TypeScript implementation)
• Rust toolchain via rustup (Rust source build)

Contributing

Contributions are welcome through focused pull requests with clear scope and passing checks. See CONTRIBUTING.md for setup and validation steps.

License

MIT. See LICENSE for details.