OmniFocus MCP Server

Retrieve ALL active projects with full details and hierarchy, optionally filtered by search query.

NEW (Phase 3.2): Added project_id and include_full_notes parameters to consolidate get_project() and get_note() functionality.

Args: project_id: NEW - Filter to specific project by ID (consolidates get_project()) include_full_notes: NEW - Return full note content (consolidates get_note()) on_hold_only: If True, only return projects with "on hold" status query: Optional search term to filter by name, note, or folder path (case-insensitive) include_task_health: If True, include per-project task health counts (remaining, available, overdue, deferred) include_last_activity: If True, compute lastActivityDate (most recent task creation/completion)

Returns: Each project includes: id, name, folderPath, status, sequential, creationDate, note (truncated unless include_full_notes=True). With include_task_health: remainingCount, availableCount, overdueCount, deferredCount, health status. With include_last_activity: lastActivityDate.

Create a new project in OmniFocus.

Args: name: The name of the project note: Optional note/description for the project (plain text only - rich text formatting is not supported via automation APIs) folder_path: Optional folder path (e.g., "Work > Clients") - folder must exist in OmniFocus sequential: If True, tasks must be completed in order — the first incomplete task is 'available' and the rest are 'blocked.' If False, all tasks are available in parallel. OmniFocus represents dependencies via task ordering in sequential projects; there are no explicit task-to-task dependency links. (default: False) review_interval_weeks: Optional review interval in weeks for GTD review cycle

Returns: Success message with project ID and configuration details

Update an existing project in OmniFocus (NEW API - Phase 2).

NEW API changes:

• Renamed 'name' to 'project_name' for consistency

• Added status parameter (active, on_hold, done, dropped)

• Added review_interval_weeks parameter

• Added last_reviewed parameter

• Added folder_path parameter

• Returns structured response with updated fields

• Consolidates: set_project_status(), drop_project(), set_review_interval(), mark_project_reviewed()

Args: project_id: The ID of the project to update project_name: New project name (optional) folder_path: Folder path to move project to (e.g., "Work : Projects") note: New note content (optional). WARNING: Removes rich text formatting. sequential: Sequential setting (optional) - "true" or "false" status: Project status - "active", "on_hold", "done", or "dropped" review_interval_weeks: Review interval in weeks (0 to clear) last_reviewed: Last reviewed date in ISO format or "now"

Returns: Success message with project ID and updated fields, or error message

Update multiple projects with the same properties (NEW API - Phase 2, Batch Function).

This is the BATCH version of update_project(). It updates multiple projects with the same values. This is more efficient than calling update_project() multiple times.

IMPORTANT: This function does NOT accept project_name or note parameters because those require unique values for each project.

Args: project_ids: Single project ID (str) or list of project IDs to update folder_path: Folder path to move projects to (e.g., "Work > Projects") sequential: Sequential setting as string ("true" or "false") status: Project status - one of: "active", "on_hold", "done", "dropped" review_interval_weeks: Review interval in weeks last_reviewed: Last review date ("now" or ISO format like "2025-01-15")

Returns: Success message with updated and failed counts, or error message

Example: # Drop multiple projects at once update_projects( project_ids=["proj-001", "proj-002", "proj-003"], status="dropped" )

Get tasks from OmniFocus with optional filtering (Enhanced - Phase 3.1).

NEW (Phase 3.1): Added task_id, parent_task_id, include_full_notes parameters to consolidate get_task(), get_subtasks(), and get_note() functionality.

Args: task_id: NEW - Filter to specific task by ID (consolidates get_task()) parent_task_id: NEW - Filter to subtasks of parent (consolidates get_subtasks()) include_full_notes: NEW - Return full note content (consolidates get_note()) project_id: Optional project ID to filter tasks (ignored if inbox_only=True) flagged_only: If True, only return flagged tasks include_completed: If True, include completed tasks (default: False) available_only: If True, only return available tasks (not blocked or deferred) overdue: If True, only return overdue tasks dropped_only: If True, only return dropped tasks blocked_only: If True, only return blocked tasks next_only: If True, only return next tasks tag_filter: List of tag names to filter by (task must have all tags) query: Optional search term to filter by name or note (case-insensitive) inbox_only: If True, only return inbox tasks

Returns: Each task includes: id, name, projectName, completed, dropped, blocked, available, next, flagged, dueDate, deferDate, estimatedMinutes, tags, note (truncated unless include_full_notes=True), parentTaskId, subtaskCount, sequential.

Create a new task in OmniFocus (NEW API - consolidates add_task and create_inbox_task).

This is the redesigned create function that unifies task creation across all contexts:

• If project_id is provided: Create task in that project

• If parent_task_id is provided: Create task as subtask under that parent

• If neither provided (or project_id=None): Create task in inbox

Args: task_name: The name/title of the task (required) project_id: Optional project ID. If None, creates in inbox (unless parent_task_id is set). Mutually exclusive with parent_task_id — a subtask inherits its parent's project. parent_task_id: Optional parent task ID to create as subtask. Mutually exclusive with project_id — a subtask inherits its parent's project. note: Optional note/description for the task (plain text only) due_date: Due date in ISO 8601 format (e.g., '2025-10-15' or '2025-10-15T17:00:00') defer_date: Defer date in ISO 8601 format (when task becomes available — hidden until then) flagged: Flag marks a task as a priority — typically 'I want to work on this today.' Flagged tasks can be queried with get_tasks(flagged_only=True). (default: False) tags: Optional JSON array string of tag names (e.g., '["Computer", "Work"]'). Tags must already exist. Note: this takes a JSON string; update_task takes a native list instead. estimated_minutes: Estimated time in minutes to complete the task

Returns: Success message with task ID and location (project/inbox/parent)

Raises: ValueError: If both project_id and parent_task_id are specified

Update an existing task in OmniFocus (NEW API - Redesign).

This comprehensive update function consolidates multiple specialized functions:

• complete_task() -> update_task(task_id, completed=True)

• drop_task() -> update_task(task_id, status="dropped")

• move_task() -> update_task(task_id, project_id=X)

• set_parent_task() -> update_task(task_id, parent_task_id=X)

• set_estimated_minutes() -> update_task(task_id, estimated_minutes=X)

• add_tag_to_task() -> update_task(task_id, add_tags=[...])

Args: task_id: The ID of the task to update task_name: New task name (optional) project_id: Move task to this project (optional). Mutually exclusive with parent_task_id — a subtask inherits its parent's project. parent_task_id: Make task a subtask of this parent (optional). Mutually exclusive with project_id — a subtask inherits its parent's project. note: New note content (optional). WARNING: Removes rich text formatting due_date: New due date in ISO 8601 format, or empty string to clear. Omitting means no change. (optional) defer_date: New defer date in ISO 8601 format (when task becomes available), or empty string to clear. Omitting means no change. (optional) flagged: Flag marks a task as a priority — typically 'I want to work on this today.' Pass True to flag, False to unflag. (optional) tags: Full replacement — set exact tag list as a native list (optional, conflicts with add_tags/remove_tags). Note: unlike create_task, this takes a list not a JSON string. add_tags: Add these tags incrementally (optional, conflicts with tags) remove_tags: Remove these tags (optional, conflicts with tags) estimated_minutes: Estimated time in minutes (optional) completed: Mark task complete/incomplete (optional) status: Task status - "active" or "dropped" (optional) name: DEPRECATED - Use task_name instead (optional, for backward compatibility)

Returns: Success message with updated fields, or error message

Examples: update_task("task-123", completed=True) # Mark complete update_task("task-123", status="dropped") # Drop task update_task("task-123", project_id="proj-456") # Move to project update_task("task-123", add_tags=["urgent"]) # Add tag update_task("task-123", task_name="New Name", flagged=True, due_date="2025-12-31")

Update multiple tasks with the same field values (batch operation - NEW API).

This is the batch version of update_task(). It applies uniform changes to multiple tasks simultaneously.

Key differences from update_task():

• Accepts Union[str, list[str]] for task_ids (single or multiple)

• Does NOT accept task_name or note (require unique values per task)

• Returns count-based summary instead of single success/failure

• Continues processing when individual tasks fail

Args: task_ids: Single task ID (str) or list of task IDs to update flagged: Flag/unflag all tasks (optional) status: Set status for all tasks - "active" or "dropped" (optional) completed: Mark all tasks complete/incomplete (optional) project_id: Move all tasks to this project (optional). Mutually exclusive with parent_task_id — a subtask inherits its parent's project. parent_task_id: Make all tasks subtasks of this parent (optional). Mutually exclusive with project_id — a subtask inherits its parent's project. tags: Full replacement - set exact tag list for all tasks (optional, conflicts with add_tags) add_tags: Add these tags to all tasks (optional, conflicts with tags) remove_tags: Remove these tags from all tasks (optional) due_date: Set due date for all tasks in ISO 8601 format, or empty string to clear. Omitting means no change. (optional) defer_date: Set defer date for all tasks in ISO 8601 format, or empty string to clear. Omitting means no change. (optional) estimated_minutes: Set estimated time in minutes for all tasks (optional)

Returns: Summary message with counts of successful/failed updates

Examples: update_tasks(["task-001", "task-002"], flagged=True) # Flag multiple tasks update_tasks("task-123", completed=True) # Complete single task (Union type) update_tasks(["task-001", "task-002", "task-003"], status="dropped") # Drop multiple

Retrieve all available tags from OmniFocus.

Tags (formerly 'contexts') represent contexts for doing work — location (Office, Home), tools (Computer, Phone), energy level (High, Low), people, or workflow states (Waiting-for, Agenda). They cut across projects and are used for filtering tasks via get_tasks(tag_filter=[...]).

Returns: Each tag includes: id, name, status.

Create a new tag in OmniFocus.

Tags (formerly 'contexts') represent contexts for doing work — location, tools, energy level, people, or workflow states. Tags can be nested (e.g., create "High" under parent "Energy" to get "Energy : High").

Args: name: The name of the tag to create parent_tag: Optional parent tag name for nesting (e.g., "Energy" to create "Energy : High"). Parent tag must already exist.

Returns: Success message with tag ID and name

Raises: ValueError: If a tag with the same name already exists

Update properties of an existing tag in OmniFocus.

Tags can be renamed or put on hold. Setting active=False puts a tag on hold — tasks with on-hold tags are excluded from available task queries.

Args: tag_id: The ID of the tag to update (from get_tags) name: New tag name (optional) active: Whether the tag is active (optional). False = on hold (tasks with this tag become unavailable). True = active.

Returns: Success message with updated fields, or error message

Delete one or more tags from OmniFocus.

WARNING: This permanently deletes the tags. Tasks that had these tags will lose the tag association but are not themselves deleted.

Args: tag_ids: Single tag ID (str) or list of tag IDs to delete

Returns: Summary of deleted tags with count and any errors encountered

Examples: delete_tags("tag-123") # Delete single tag delete_tags(["tag-001", "tag-002"]) # Delete multiple

Delete multiple tasks from OmniFocus in a single operation (NEW API - Enhanced).

WARNING: This permanently deletes the tasks and cannot be undone.

NEW API (Redesign): Now accepts Union[str, list[str]] and handles dict return from client.

Args: task_ids: Single task ID (str) or list of task IDs to delete

Returns: Summary of deleted tasks with count and any errors encountered

Examples: delete_tasks("task-123") # Delete single task delete_tasks(["task-001", "task-002", "task-003"]) # Delete multiple

Delete one or more projects from OmniFocus (NEW API - Enhanced with Union type).

WARNING: This permanently deletes the projects and all their tasks. Cannot be undone.

NEW API changes:

• Accepts Union[str, list[str]] for project_ids (single or multiple)

• Returns detailed summary with success/failure counts

Args: project_ids: Single project ID (str) or list of project IDs to delete

Returns: Summary of deleted projects with count and any errors encountered

Get all folders from OmniFocus with their hierarchy.

Returns: Formatted hierarchical list of all folders with indentation showing nesting

Create a new folder in OmniFocus.

Args: name: The name of the folder to create parent_path: Optional parent folder path (e.g., "Work" or "Work > Clients")

Returns: Success message with folder ID and full path

Move a task before or after another task to change its position.

Use this to reorder tasks within a project or within a parent task's subtasks. In sequential projects, task order determines dependencies — reordering changes which task is available next (first incomplete = available, rest = blocked).

Args: task_id: The ID of the task to move before_task_id: Move the task before this task (provide either this OR after_task_id) after_task_id: Move the task after this task (provide either this OR before_task_id)

Returns: Success message confirming the task was reordered

Note: Both tasks must be in the same project and at the same level (both root-level or both subtasks of the same parent). Exactly one of before_task_id or after_task_id must be provided.

Get all perspectives from OmniFocus with type and ID information.

Returns: Formatted list of perspectives with name, type (built-in/custom), and ID

Switch the front window to a different perspective.

Args: perspective_name: Name of the perspective to switch to

Returns: Success message confirming perspective switch

Set focus on one or more items, or clear focus.

OmniFocus supports focusing on projects and folders only. Call with no arguments (or empty lists) to clear focus.

Args: item_ids: Single ID or list of IDs to focus on. Omit or pass empty to clear. item_types: Matching type(s) - each must be "project" or "folder".

Returns: Success message confirming focus set or cleared

Get the currently focused items in OmniFocus.

Returns: Formatted list of currently focused items, or a message if no focus is set