Add a tag to a task in OmniFocus.

Use either the task ID or task name to identify the task.

Args:

• taskId (string, optional): The task's ID. Takes priority if both taskId and taskName provided.

• taskName (string, optional): The task's name to search for. At least one of taskId or taskName is required.

• tagName (string): Name of the tag to add

Returns: The updated task object

Examples:

• By ID: { taskId: "abc123", tagName: "Urgent" }

• By name: { taskName: "Write report", tagName: "Urgent" }

Add the same tag to multiple tasks in one operation.

The tag must already exist. Tasks that already have the tag are left unchanged.

Args:

• taskIds (array): Array of task IDs to tag (1-100)

• tagName (string): Name of the tag to add

Returns: Summary with counts and the updated tasks, plus any per-task failures

Examples:

• Tag several tasks: { taskIds: ["id1", "id2"], tagName: "Urgent" }

Complete or drop multiple tasks in one operation.

Args:

• taskIds (array): Array of task IDs to complete or drop (1-100)

• action (string): 'complete' (default) or 'drop'

Returns: Summary with counts and the updated tasks, plus any per-task failures

Examples:

• Complete several: { taskIds: ["id1", "id2", "id3"] }

• Drop several: { taskIds: ["id1", "id2"], action: "drop" }

Mark multiple projects as reviewed in one operation.

Efficiently updates the review status for multiple projects at once.

Args:

• projectIds (array): Array of project IDs to mark as reviewed (1-100 projects)

• reviewIntervalDays (number, optional): Custom review interval in days (1-3650) to apply to all projects

Returns: Summary with count of successfully reviewed projects and any errors

Examples:

• Review multiple projects: { projectIds: ["id1", "id2", "id3"] }

• With custom interval: { projectIds: ["id1", "id2"], reviewIntervalDays: 14 }

Remove the same tag from multiple tasks in one operation.

Tasks that do not have the tag are left unchanged.

Args:

• taskIds (array): Array of task IDs to untag (1-100)

• tagName (string): Name of the tag to remove

Returns: Summary with counts and the updated tasks, plus any per-task failures

Examples:

• Untag several tasks: { taskIds: ["id1", "id2"], tagName: "Waiting" }

Mark a task as complete or dropped in OmniFocus.

Use either the task ID from list/search results, or the task name for natural language interactions.

Args:

• taskId (string, optional): The task's ID (primaryKey). Takes priority if both taskId and taskName provided.

• taskName (string, optional): The task's name to search for. At least one of taskId or taskName is required.

• action (string): 'complete' (default) or 'drop'

Note: Completing a recurring task advances it to the next occurrence (normal repeat behavior). Dropping a recurring task cancels the whole series - its repetition rule is removed first so it does not roll forward to a new active instance.

Returns: The updated task object

Examples:

• Complete by ID: { taskId: "abc123" }

• Complete by name: { taskName: "Write documentation" }

• Drop by name: { taskName: "Old task", action: "drop" }

Create a new folder in OmniFocus.

Creates a folder at the top level or nested inside an existing folder.

Args:

• name (string): Folder name (required)

• parentFolderName (string, optional): Parent folder to nest inside (top level if omitted)

Returns: The created folder object with id, name, and other properties

Examples:

• Top-level folder: { name: "Work" }

• Nested folder: { name: "Q1", parentFolderName: "Work" }

Create a new project in OmniFocus.

Creates a project at the top level or inside a specific folder. Optional properties like due date, defer date, flags, and sequential ordering can be set.

Args:

• name (string): Project name (required)

• note (string): Optional note/description

• folderName (string): Folder to place the project in (top level if omitted)

• dueDate (string): Due date in ISO 8601 format

• deferDate (string): Defer/start date in ISO 8601 format

• flagged (boolean): Flag the project (default: false)

• sequential (boolean): Tasks must be done in order (default: false = parallel)

• status (string): "active", "on hold", "done", or "dropped" (default: "active")

Returns: The created project object with id, name, and other properties

Examples:

• Simple project: { name: "Launch website" }

• In a folder: { name: "Q1 Planning", folderName: "Work" }

• With details: { name: "Write book", dueDate: "2024-12-31T17:00:00", sequential: true, flagged: true }

Create a new task in OmniFocus.

Creates a task in the inbox or a specific project. Tags, due dates, planned dates and other properties can be set. Supports repeating/recurring tasks.

Args:

• name (string): Task name/title (required)

• note (string): Optional note/description

• projectName (string): Project to add to (inbox if not specified)

• parentTaskId (string): ID of a parent task to create this as a subtask of (takes priority over projectName)

• dueDate (string): Due date in ISO 8601 format - when the task must be completed

• deferDate (string): Defer/start date in ISO 8601 format

• plannedDate (string): Planned date in ISO 8601 format - when you intend to work on the task

• flagged (boolean): Flag the task (default: false)

• estimatedMinutes (number): Time estimate in minutes

• tagNames (array): Tag names to apply

• recurrence (object): Optional recurrence pattern with:

  • frequency: "daily", "weekly", "monthly", or "yearly"

  • interval: Number of periods between repetitions (default: 1)

  • daysOfWeek: Array of days for weekly recurrence (e.g., ["Monday", "Friday"])

  • dayOfMonth: Day number for monthly recurrence (1-31)

  • monthOfYear: Month number for yearly recurrence (1-12)

  • repeatFrom: "due-date" or "completion-date" (default: "due-date")

Returns: The created task object with id, name, and other properties

Examples:

• Simple task: { name: "Buy groceries" }

• Task with details: { name: "Review report", projectName: "Work", dueDate: "2024-12-31T17:00:00", flagged: true }

• Daily recurring: { name: "Daily standup", dueDate: "2024-01-01T09:00:00", recurrence: { frequency: "daily", interval: 1 } }

• Weekly on Mon/Wed/Fri: { name: "Workout", dueDate: "2024-01-01T07:00:00", recurrence: { frequency: "weekly", daysOfWeek: ["Monday", "Wednesday", "Friday"] } }

• Monthly on 1st and 15th: { name: "Pay bills", dueDate: "2024-01-01T12:00:00", recurrence: { frequency: "monthly", interval: 1, dayOfMonth: 1 } }

• Repeat from completion: { name: "Review quarterly", recurrence: { frequency: "monthly", interval: 3, repeatFrom: "completion-date" } }

• Task with planning: { name: "Write article", plannedDate: "2024-12-15T09:00:00", dueDate: "2024-12-31T17:00:00" }

• Task with tags: { name: "Call John", tagNames: ["Calls", "Urgent"] }

Permanently delete a folder from OmniFocus, including any projects and folders it contains. This cannot be undone via MCP.

Use either the folder ID from list/search results, or the folder name.

Args:

• folderId (string, optional): The folder's ID. Takes priority if both folderId and folderName provided.

• folderName (string, optional): The folder's name to search for. At least one of folderId or folderName is required.

Returns: Confirmation message with the deleted folder's name

Examples:

• Delete by ID: { folderId: "abc123" }

• Delete by name: { folderName: "Old folder" }

Permanently delete a project from OmniFocus, including its tasks. This cannot be undone via MCP.

Use either the project ID from list/search results, or the project name.

Args:

• projectId (string, optional): The project's ID. Takes priority if both projectId and projectName provided.

• projectName (string, optional): The project's name to search for. At least one of projectId or projectName is required.

Returns: Confirmation message with the deleted project's name

Examples:

• Delete by ID: { projectId: "abc123" }

• Delete by name: { projectName: "Old project" }

Permanently delete a task from OmniFocus. This cannot be undone via MCP.

Use either the task ID from list/search results, or the task name.

Args:

• taskId (string, optional): The task's ID. Takes priority if both taskId and taskName provided.

• taskName (string, optional): The task's name to search for. At least one of taskId or taskName is required.

Returns: Confirmation message with the deleted task's name

Examples:

• Delete by ID: { taskId: "abc123" }

• Delete by name: { taskName: "Old draft" }

Get tasks that are due within a specified timeframe.

Args:

• daysAhead (number): Days to look ahead, 0-365 (default: 7)

• includeOverdue (boolean): Include overdue tasks (default: true)

• limit (number): Max tasks, 1-500 (default: 50)

• tags (array, optional): Filter to tasks matching these tag names (max 20)

• tagMatchMode (string): How to match tags - 'all', 'any', or 'none' (default 'all'). Only applied when tags is provided.

Returns: Array of due tasks sorted by due date

Examples:

• Due this week: {}

• Due today: { daysAhead: 0 }

• Due in 30 days: { daysAhead: 30 }

Get all flagged tasks in OmniFocus.

Args:

• includeCompleted (boolean): Include completed tasks (default: false)

• limit (number): Max tasks, 1-500 (default: 50)

• tags (array, optional): Filter to tasks matching these tag names (max 20)

• tagMatchMode (string): How to match tags - 'all', 'any', or 'none' (default 'all'). Only applied when tags is provided.

Returns: Array of flagged tasks

Examples:

• Active flagged: {}

• All flagged: { includeCompleted: true }

Get tasks shown in a specific OmniFocus perspective.

Switches the front OmniFocus window to the named perspective, reads the tasks it displays, then restores the original perspective.

Args:

• perspectiveName (string): Name of the perspective (use omnifocus_list_perspectives to find names)

• limit (number): Maximum tasks to return, 1-500 (default: 50)

Returns: Array of task objects with: id, name, note, completed, flagged, dueDate, deferDate, projectName, tags, estimatedMinutes

Examples:

• Get tasks from a perspective: { perspectiveName: "Next" }

• With limit: { perspectiveName: "Forecast", limit: 10 }

Get tasks that are planned within a specified timeframe.

Planned dates represent when you intend to work on a task, separate from the due date.

Args:

• daysAhead (number): Days to look ahead, 0-365 (default: 7)

• includeOverdue (boolean): Include overdue planned tasks (default: true)

• limit (number): Max tasks, 1-500 (default: 50)

• tags (array, optional): Filter to tasks matching these tag names (max 20)

• tagMatchMode (string): How to match tags - 'all', 'any', or 'none' (default 'all'). Only applied when tags is provided.

Returns: Array of planned tasks sorted by planned date

Examples:

• Planned this week: {}

• Planned today: { daysAhead: 0 }

• Planned in 30 days: { daysAhead: 30 }

Get projects that need review based on their next review date.

Returns projects whose next review date is on or before today (or within specified days ahead).

Args:

• daysAhead (number): Days to look ahead, 0-365 (default: 0 = overdue only)

• status (string): Filter by status - 'all', 'active', 'done', 'dropped', 'onHold' (default: 'active')

• limit (number): Maximum projects to return, 1-500 (default: 50)

Returns: Array of projects needing review sorted by next review date

Examples:

• Overdue reviews: {}

• Reviews due within 7 days: { daysAhead: 7 }

• All active projects due for review: { status: "active", daysAhead: 30 }

Get all tasks belonging to a specific project in OmniFocus.

Returns the tasks within a project, including subtasks. Use omnifocus_list_projects to find project IDs first.

Args:

• projectId (string): The ID of the project

• includeCompleted (boolean): Include completed tasks (default: false)

• limit (number): Maximum tasks to return, 1-500 (default: 100)

Returns: Array of task objects with: id, name, note, completed, flagged, dueDate, deferDate, estimatedMinutes, tags, parentTaskId, parentTaskName, hasChildren, childTaskCount

Examples:

• Get tasks for a project: { projectId: "abc123" }

• Include completed: { projectId: "abc123", includeCompleted: true }

List folders in OmniFocus.

Folders are used to organize projects hierarchically.

Args:

• status (string): Filter by status - 'all', 'active', 'dropped' (default: 'active')

• limit (number): Maximum folders to return, 1-200 (default: 50)

Returns: Array of folder objects with: id, name, status, projectCount, folderCount, parentName

Examples:

• List active folders: {}

• List all folders: { status: "all" }

List tasks in the OmniFocus inbox.

Returns tasks that haven't been assigned to a project yet. These are typically newly captured items awaiting processing.

Args:

• includeCompleted (boolean): Include completed tasks (default: false)

• limit (number): Maximum tasks to return, 1-500 (default: 50)

• tags (array, optional): Filter to tasks matching these tag names (max 20)

• tagMatchMode (string): How to match tags - 'all' (every tag), 'any' (at least one), 'none' (none of them). Default 'all'. Only applied when tags is provided.

Returns: Array of task objects with: id, name, note, completed, flagged, dueDate, deferDate, estimatedMinutes, tags

Examples:

• List all inbox items: {}

• Include completed: { includeCompleted: true }

• Only untagged-by-Work items: { tags: ["Work"], tagMatchMode: "none" }

List perspectives in OmniFocus.

Perspectives are saved views/filters that show specific subsets of tasks. Includes both built-in and custom perspectives.

Args:

• limit (number): Maximum perspectives to return, 1-200 (default: 50)

Returns: Array of perspective objects with: id, name

Examples:

• List perspectives: {}

• Limit results: { limit: 10 }

List projects in OmniFocus.

Returns projects with their status, dates, and folder information.

Args:

• status (string): Filter by status - 'all', 'active', 'done', 'dropped', 'onHold' (default: 'active')

• folderName (string): Optional folder name filter (partial match)

• limit (number): Maximum projects to return, 1-500 (default: 50)

Returns: Array of project objects with: id, name, note, status, completed, flagged, dueDate, deferDate, folderName, taskCount, sequential

Examples:

• List active projects: {}

• List all projects: { status: "all" }

• Projects in a folder: { folderName: "Work" }

List tags in OmniFocus.

Tags (formerly contexts) are used to categorize tasks by context, person, tool, etc.

Args:

• status (string): Filter by status - 'all', 'active', 'onHold', 'dropped' (default: 'active')

• limit (number): Maximum tags to return, 1-200 (default: 50)

Returns: Array of tag objects with: id, name, status, taskCount, allowsNextAction, parentName

Examples:

• List active tags: {}

• List all tags: { status: "all" }

Mark a project as reviewed and update its next review date.

Use either the project ID or project name to identify the project. The next review date will be set based on the project's review interval or a custom interval if provided.

Args:

• projectId (string, optional): The project's ID. Takes priority if both projectId and projectName provided.

• projectName (string, optional): The project's name to search for. At least one of projectId or projectName is required.

• reviewIntervalDays (number, optional): Custom review interval in days (1-3650). If not provided, uses the project's current review interval.

Returns: The updated project object

Examples:

• By ID: { projectId: "abc123" }

• By name: { projectName: "Work Project" }

• With custom interval: { projectName: "Weekly Project", reviewIntervalDays: 7 }

Remove a tag from a task in OmniFocus.

Use either the task ID or task name to identify the task.

Args:

• taskId (string, optional): The task's ID. Takes priority if both taskId and taskName provided.

• taskName (string, optional): The task's name to search for. At least one of taskId or taskName is required.

• tagName (string): Name of the tag to remove

Returns: The updated task object

Examples:

• By ID: { taskId: "abc123", tagName: "Urgent" }

• By name: { taskName: "Old task", tagName: "Done" }

Search for tasks, projects, folders, or tags in OmniFocus.

Uses OmniFocus's smart matching to find items.

Args:

• query (string): Search query

• searchType (string): 'tasks', 'projects', 'folders', 'tags', or 'all' (default: 'all')

• limit (number): Max results per type, 1-100 (default: 20)

Returns: Matching items organized by type

Examples:

• Search all: { query: "report" }

• Search projects only: { query: "work", searchType: "projects" }

Rename an existing folder in OmniFocus.

Args:

• folderId (string, optional): The folder's ID. Takes priority if both folderId and folderName provided.

• folderName (string, optional): The folder's name to search for. At least one of folderId or folderName is required.

• name (string): New folder name

Note: moving a folder into another folder is not supported by OmniFocus's JXA layer (the move operation is rejected). Recreate the folder in the target location if you need to move it.

Returns: The updated folder object

Examples:

• Rename by ID: { folderId: "abc123", name: "Archive" }

• Rename by name: { folderName: "Q1", name: "Q1 2027" }

Update properties of an existing project in OmniFocus.

Only the fields you provide are changed. Use null to clear a date or note field.

Args:

• projectId (string, optional): The project's ID. Takes priority if both projectId and projectName provided.

• projectName (string, optional): The project's name to search for. At least one of projectId or projectName is required.

• name (string, optional): New project name

• note (string | null, optional): New note text. Pass null to clear.

• status (string, optional): "active", "on hold", "done", or "dropped". Setting "done" completes the project and "dropped" drops it (setting "active" reactivates a completed/dropped project).

• flagged (boolean, optional): Set flagged state

• dueDate (string | null, optional): New due date in ISO 8601 format. Pass null to clear.

• deferDate (string | null, optional): New defer date in ISO 8601 format. Pass null to clear.

• sequential (boolean, optional): Tasks must be done in order (true) or parallel (false)

• reviewIntervalDays (number, optional): Review interval in days (1-3650)

Note: moving a project between folders is not supported by OmniFocus's JXA layer (the move operation returns "Replacement not supported"). Recreate the project in the target folder if you need to move it.

Returns: The updated project object

Examples:

• Rename: { projectId: "abc123", name: "New name" }

• Put on hold: { projectId: "abc123", status: "on hold" }

• Complete the project: { projectId: "abc123", status: "done" }

• Drop the project: { projectId: "abc123", status: "dropped" }

• Set review interval: { projectId: "abc123", reviewIntervalDays: 14 }

• Clear due date: { projectId: "abc123", dueDate: null }

Update the note/description on an existing project in OmniFocus.

Use either the project ID or project name to identify the project.

Args:

• projectId (string, optional): The project's ID. Takes priority if both projectId and projectName provided.

• projectName (string, optional): The project's name to search for. At least one of projectId or projectName is required.

• note (string): The new note content. Use empty string to clear the note.

• append (boolean): If true, append to existing note instead of replacing (default: false)

Returns: The updated project object

Examples:

• Set note by ID: { projectId: "abc123", note: "Q1 deliverables" }

• Set note by name: { projectName: "Work Project", note: "Started Jan 2024" }

• Clear note: { projectId: "abc123", note: "" }

• Append to note: { projectId: "abc123", note: "\nNew update", append: true }

Update properties of an existing task in OmniFocus.

Only the fields you provide are changed. Use null to clear a date or note field.

Args:

• taskId (string, optional): The task's ID. Takes priority if both taskId and taskName provided.

• taskName (string, optional): The task's name to search for. At least one of taskId or taskName is required.

• name (string, optional): New task name

• note (string | null, optional): New note text. Pass null to clear.

• dueDate (string | null, optional): New due date in ISO 8601 format. Pass null to clear.

• deferDate (string | null, optional): New defer date in ISO 8601 format. Pass null to clear.

• plannedDate (string | null, optional): New planned date in ISO 8601 format. Pass null to clear.

• flagged (boolean, optional): Set flagged state

• estimatedMinutes (number, optional): Time estimate in minutes. Pass 0 to clear.

• projectId (string, optional): ID of the project to move the task to.

• projectName (string, optional): Name of the project to move the task to. Ignored if projectId is provided.

• recurrence (object | null, optional): Repetition pattern to make the task recurring (same shape as create_task: frequency, interval, daysOfWeek, dayOfMonth, monthOfYear, repeatFrom). Pass null to remove recurrence.

• clearRecurrence (boolean, optional): Set true to remove the task's repetition rule (turn off recurring). Equivalent to recurrence: null.

Returns: The updated task object

Examples:

• Rename: { taskId: "abc123", name: "New name" }

• Set due date: { taskId: "abc123", dueDate: "2024-12-31T17:00:00" }

• Clear due date: { taskId: "abc123", dueDate: null }

• Make it recurring weekly: { taskId: "abc123", recurrence: { frequency: "weekly", daysOfWeek: ["Monday"] } }

• Turn off recurring: { taskId: "abc123", clearRecurrence: true }

• Flag and estimate: { taskId: "abc123", flagged: true, estimatedMinutes: 30 }

Update the note/description on an existing task in OmniFocus.

Use either the task ID or task name to identify the task.

Args:

• taskId (string, optional): The task's ID. Takes priority if both taskId and taskName provided.

• taskName (string, optional): The task's name to search for. At least one of taskId or taskName is required.

• note (string): The new note content. Use empty string to clear the note.

• append (boolean): If true, append to existing note instead of replacing (default: false)

Returns: The updated task object

Examples:

• Set note by ID: { taskId: "abc123", note: "Remember to include charts" }

• Set note by name: { taskName: "Write report", note: "Draft due Friday" }

• Clear note: { taskId: "abc123", note: "" }

• Append to note: { taskId: "abc123", note: "\nAdditional info here", append: true }