OmniFocus MCP Server
Provides tools for interacting with the OmniFocus application on macOS, enabling project and task management, folder organization, tag handling, and UI navigation via AppleScript.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OmniFocus MCP Server add a task to review the project proposal due tomorrow at 5pm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OmniFocus MCP Server
A comprehensive, fast, reliable, and agent-friendly MCP server for OmniFocus on macOS.
Why This Server
Comprehensive
21 tools covering projects, tasks, folders, tags, perspectives, and focus. Full CRUD with unified batch operations (Pydantic model inputs), 20+ filter types on task and project queries, and date management including recurrence (RRULE read/write).
Fast
Sub-second reads on filtered queries, even with hundreds of tasks in the database.
Operation | Time | Items | Database |
Get flagged tasks | 0.66s | 14 | 202 tasks |
Get overdue tasks | 0.69s | 8 | 202 tasks |
Get next tasks | 0.66s | 27 | 202 tasks |
Get inbox tasks | 0.64s | 10 | 202 tasks |
Search tasks by keyword | 1.07s | 37 | 202 tasks |
Get all tasks (unfiltered) | 2.20s | 202 | 202 tasks |
Get all projects | 0.57s | 35 | 35 projects |
Create or update a task | 0.9s | — | — |
Full profiling data: PERFORMANCE_PROFILING.md
Reliable
93% code coverage from 1027 unit tests. 192 integration and E2E tests run against real OmniFocus, plus 5 protocol-level smoke tests verifying the full MCP JSON-RPC transport. Tests cover task, project, and tag lifecycles, filtering, hierarchy, dates, recurrence, and review workflows.
Agent-Friendly
73-scenario blind eval suite with frontier models scoring 100% and popular open-weight models scoring 90-94% (full results). Agents that have never seen OmniFocus can correctly use every tool from descriptions alone. Scenarios cover tool selection, parameter usage, multi-step workflows, date semantics, recurrence, tag behavior, task movement, text search, and safety-critical operations (drop vs delete, destructive action guardrails). Server instructions teach GTD concepts (task states, project types, sequential dependencies, review cycles) so agents make informed decisions, not just API calls.
Related MCP server: OmniFocus MCP Server
Tools (21)
Projects (6)
get_projects — filter by ID, query, status; includes dates, review info, task health, stalled detection
create_project — with folder placement, dates, review interval, project type
update_project — all properties: name, note, status, dates, folder, review settings
update_projects — batch update (status, dates, folder, review settings)
delete_projects — single or batch
reorder_project — position relative to siblings within a folder (before/after)
Tasks (6)
get_tasks — 14 filter types: by ID, project, parent, tags, status, dates, flags, text search, inbox
create_task — with dates, tags, flags, estimated time, parent task, sequential
update_task — all properties including recurrence (RRULE), tags (replace/add/remove), hierarchy
update_tasks — batch update (dates, flags, tags, status, project)
delete_tasks — single or batch
reorder_task — position relative to siblings (before/after)
Folders (3)
get_folders — hierarchy with paths
create_folder — with optional parent
update_folder — rename or move to different parent
Tags (4)
get_tags — with status and mutual exclusivity info
create_tag — with parent nesting and exclusivity
update_tag — name, status, exclusivity
delete_tags — single or batch
Perspectives (2)
get_perspectives — list with type info
switch_perspective — navigate to perspective
Navigation (2)
set_focus — focus on projects/folders or clear
get_focus — current focus state
Prerequisites
macOS with OmniFocus installed
Python 3.10+
uv package manager
Installation
git clone https://github.com/s-morgan-jeffries/omnifocus-mcp.git
cd omnifocus-mcp
git checkout v0.13.2 # Latest stable release
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync --devConfiguration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"omnifocus": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/omnifocus-mcp",
"run",
"omnifocus-mcp"
]
}
}
}Other MCP Clients
python -m omnifocus_mcp.server_fastmcpCommunicates via stdin/stdout using the MCP protocol.
Permissions
macOS will prompt for:
Accessibility access (to control OmniFocus via AppleScript)
Automation permissions for OmniFocus
Contributing
Bug reports and feature requests are welcome via GitHub Issues.
License
MIT
Available Tools
21 toolscreate_foldersB
Create one or more folders.
Parameters (per item):
name: str (required)
parent_path: str -- e.g. "Work > Clients"
Inputs: folders (required). Returns: result
create_projectsA
Create one or more projects.
Parameters (per item):
name: str (required)
note, folder_path: str
project_type: str -- "parallel" (default), "sequential", "single_actions"
sequential: bool (deprecated, use project_type)
review_interval_value: int + review_interval_unit: str ("day"/"week"/"month"/"year"); review_interval_weeks: int (deprecated)
completed_by_children: bool
due_date, defer_date, planned_date: str -- ISO 8601
Inputs: projects (required). Returns: result
create_tagsB
Create one or more tags.
Parameters (per item):
name: str (required)
parent_tag: str -- parent by name
children_are_mutually_exclusive: bool
Inputs: tags (required). Returns: result
create_tasksA
Create one or more tasks.
Parameters (per item):
task_name: str (required)
project_id: str -- mutually exclusive with parent_task_id
parent_task_id: str -- creates subtask
note: str (plain text only)
due_date, defer_date, planned_date: str -- ISO 8601
flagged: bool
tags: list[str] -- must already exist
estimated_minutes: int
sequential: bool -- subtasks completed in order
completed_by_children: bool
Inputs: tasks (required). Returns: result
delete_projectsA
Permanently delete projects and all their tasks. Cannot be undone.
project_ids: str | list[str] (required)
Inputs: project_ids (required). Returns: result
delete_tagsB
Delete tags. Tasks lose tag association but are not deleted.
tag_ids: str | list[str] (required)
Inputs: tag_ids (required). Returns: result
delete_tasksC
Permanently delete tasks. Cannot be undone.
task_ids: str | list[str] (required)
Inputs: task_ids (required). Returns: result
get_focusB
Get currently focused items.
Inputs: no named parameters. Returns: result
get_foldersB
Get all folders with hierarchy.
Returns: id, name, path (e.g. "Work > Clients"), status ("active"/"dropped").
Inputs: no named parameters. Returns: result
get_perspectivesA
Get all perspectives.
Returns: name, type (built-in/custom), id
Inputs: no named parameters. Returns: result
get_projectsA
Retrieve projects with optional filtering.
Parameters:
project_id: str -- filter to specific project
query: str -- search name/note/folder (case-insensitive)
flagged_only, on_hold_only, completed_only: bool
stalled_only: bool -- active projects with no available next actions
include_dropped, include_completed: bool -- include hidden states
include_full_notes: bool
include_task_health: bool -- adds remainingCount, availableCount, overdueCount, deferredCount, stalled, health
include_last_activity: bool -- adds lastActivityDate
has_overdue_tasks: bool -- implies include_task_health
tag_filter: list[str] -- projects with ALL specified tags
due_after, due_before, due_on: str -- ISO date filters for due date
defer_after, defer_before, defer_on: str -- ISO date filters for defer date
planned_after, planned_before, planned_on: str
completion_after, completion_before, completion_on: str
dropped_after, dropped_before, dropped_on: str
created_after, created_before, created_on: str
modified_after, modified_before, modified_on: str
min_task_count: int
has_no_due_dates: bool
sort_by: str -- "name", "due_date", "defer_date", "planned_date", "creation_date", "modification_date", "completion_date", "dropped_date"; sort_order: str -- "asc"/"desc"
Returns: id, name, folderPath, status, projectType, sequential (deprecated), completedByChildren, flagged, creationDate, modificationDate, completionDate, droppedDate, dueDate, deferDate, plannedDate, tags, note, lastReviewDate, nextReviewDate, reviewIntervalValue, reviewIntervalUnit. Optional health/activity fields when requested.
Inputs: project_id, include_full_notes, on_hold_only, query, +34 more. Returns: result
get_tagsA
Retrieve all tags.
Returns: id, name, status ("active"/"on hold"/"dropped"), parentTagId (empty if top-level; create/update accept parent by NAME not ID), childrenAreMutuallyExclusive (assigning one child silently removes siblings).
Inputs: no named parameters. Returns: result
get_tasksA
Get tasks with optional filtering.
Parameters:
task_id, parent_task_id, project_id: str
query: str -- search name/note
flagged_only, available_only, overdue, dropped_only, blocked_only, next_only, inbox_only: bool
include_completed: bool
include_full_notes: bool
tag_filter: list[str]; tag_filter_mode: str -- "and" (default), "or", "not"
due_after, due_before, due_on: str -- ISO date filters for due date
defer_after, defer_before, defer_on: str -- ISO date filters for defer date
planned_after, planned_before, planned_on: str
completion_after, completion_before, completion_on: str -- requires include_completed
dropped_after, dropped_before, dropped_on: str -- requires dropped_only or include_completed
modified_after, modified_before, modified_on, created_after, created_before, created_on: str
max_estimated_minutes: int -- quick wins filter
has_estimate: bool
recurring_only: bool
sort_by: str -- "name", "due_date", "defer_date", "planned_date", "creation_date", "modification_date", "completion_date", "dropped_date"; sort_order: str
Returns: id, name, projectName, completed, dropped, blocked, available, next, flagged, dueDate, deferDate, plannedDate, estimatedMinutes, tags, note, parentTaskId, subtaskCount, sequential, isRecurring, recurrence, repetitionMethod, repeatSummary, nextDueDate, nextDeferDate, nextPlannedDate, catchUpAutomatically, creationDate, modificationDate, completionDate, droppedDate.
Key fields:
available -- true when actionable (accounts for inherited status from containers)
repeatSummary -- human-readable recurrence; always use this for display, don't parse RRULE
repetitionMethod -- "fixed" (original schedule), "start_after_completion" (defer shifts), "due_after_completion" (due shifts)
catchUpAutomatically -- recurring only; true = one catch-up occurrence, false = each missed interval spawns its own
Date fields are effective (include inherited from project). Next-occurrence fields populated only for recurring tasks.
Tasks inherit tags from their parent project. A task showing a tag it wasn't explicitly assigned has inherited it -- this is expected, not a bug.
Inputs: task_id, parent_task_id, include_full_notes, project_id, +37 more. Returns: result
reorder_projectA
Move a project before or after another project within the same folder.
project_id: str (required)
before_project_id: str
after_project_id: str
Exactly one of before/after required.
Inputs: project_id (required), before_project_id, after_project_id. Returns: result
reorder_taskA
Move a task before or after another task within the same project/level.
task_id: str (required)
before_task_id: str -- place before this task
after_task_id: str -- place after this task
Exactly one of before/after required. In sequential projects, order = dependencies.
Inputs: task_id (required), before_task_id, after_task_id. Returns: result
set_focusA
Focus on projects/folders, or clear focus. Does not support tasks or tags.
item_ids: str | list[str] -- omit or empty to clear
item_types: str | list[str] -- "project" or "folder"
Inputs: item_ids, item_types. Returns: result
switch_perspectiveC
Switch front window to a perspective.
perspective_name: str (required)
Inputs: perspective_name (required). Returns: result
update_foldersA
Update one or more folders. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
name: str
status: str -- "active" or "dropped"
Inputs: folders (required). Returns: result
update_projectsA
Update one or more projects. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
project_name, note, folder_path: str -- note: replaces rich text
project_type: str; sequential: bool (deprecated)
status: str -- "active", "on_hold", "done", "dropped"
review_interval_value: int + review_interval_unit: str ("day"/"week"/"month"/"year"); review_interval_weeks: int (deprecated)
last_reviewed: str -- ISO or "now" (recalculates next_review_date from review interval)
next_review_date: str -- set AFTER last_reviewed to override the calculated date
completed_by_children: bool
due_date, defer_date, planned_date: str -- ISO or "" to clear
flagged: bool
estimated_minutes: int
tags: list[str] -- full replacement (conflicts with add_tags/remove_tags)
add_tags, remove_tags: list[str]
recurrence: str -- RRULE or "" to clear; repetition_method: str -- "fixed", "start_after_completion", "due_after_completion"
Inputs: projects (required). Returns: result
update_tagsB
Update one or more tags. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
name, status: str -- status: "active", "on_hold", "dropped"
children_are_mutually_exclusive: bool
parent_tag: str -- move to parent by name, "" for top level
Inputs: tags (required). Returns: result
update_tasksA
Update one or more tasks. Each item has id (required) plus fields to change.
Parameters (per item):
id: str (required)
task_name, project_id, parent_task_id, note: str
due_date, defer_date, planned_date: str -- ISO or "" to clear
flagged, completed: bool -- completed=True on recurring task creates next occurrence
status: str -- "dropped" (prefer completed: bool for completion)
tags: list[str] -- full replacement (conflicts with add_tags/remove_tags)
add_tags, remove_tags: list[str]
estimated_minutes: int
recurrence: str -- RRULE or "" to clear; repetition_method: str
sequential: bool; completed_by_children: bool
Inputs: tasks (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct entity or action (folders, projects, tags, tasks, focus, perspectives) with clear CRUD separation. No two tools have overlapping purposes.
All tools follow a consistent verb_noun pattern, using plural for collections (create_folders, get_projects) and singular for singular concepts (get_focus, switch_perspective). No mixing of conventions.
21 tools is slightly above the typical range but well-justified by the domain's complexity, covering multiple entities and operations like reordering and focus management. Still feels well-scoped without redundancy.
CRUD operations for all main entities exist, plus focus and perspective management. Minor gaps like perspective CRUD or advanced note handling are absent but core task management workflows are fully covered.
Maintenance
Related MCP Connectors
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage projects, tasks, time tracking, and team collaboration through natural language.
Capture, clarify and plan your tasks from Claude or ChatGPT: inbox, next actions and projects.
Tasks, projects, next steps and notes in one app your AI reads and writes.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnhanced Model Context Protocol server that transforms OmniFocus into an AI-powered productivity tool with comprehensive task management capabilities including subtask support, perspective views, advanced filtering, and custom perspective access.25155 npm67MIT
- AlicenseBqualityBmaintenanceEnables AI-powered task management in OmniFocus with support for project reviews, planned dates, repeating tasks, custom perspectives, hierarchical subtasks, and advanced filtering. Perfect for Claude AI integration with comprehensive CRUD operations for tasks, projects, and folders.313MIT
- AlicenseBqualityCmaintenanceA comprehensive MCP server for OmniFocus 4 on macOS featuring 34 tools for task management, project organization, and advanced filtering. It enables full CRUD operations for tasks, projects, folders, and tags while supporting custom perspectives and complex repetition rules.536MIT
- AlicenseAqualityDmaintenanceGives MCP-compatible AI assistants full, typed access to OmniFocus on macOS, enabling task management, project manipulation, inbox processing, and more via natural language.10027 npm2MIT