OmniFocus MCP Server

A Model Context Protocol (MCP) server that connects OmniFocus to Claude and other MCP-compatible AI assistants.

Overview

This server bridges AI assistants and your OmniFocus database. Through natural conversation, an assistant can query, create, edit, and remove tasks and projects — including bulk operations. Some things you can do with it:

• Translate a syllabus PDF into a fully specified project with tasks, tags, defer dates, and due dates
• Turn a meeting transcript into a list of actions
• Audit and reorganize your tags, projects, and folders conversationally
• Create visualizations of your tasks, projects, and tags
• Process dozens of items in a single batch operation

Quick Start

Prerequisites

• macOS with OmniFocus installed
• Node.js 20 or later (for npx)

The first time the server talks to OmniFocus, macOS will ask you to allow automation access. Grant it once and you're set.

Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Then restart Claude Desktop.

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp

Other MCP clients work the same way: launch npx -y omnifocus-mcp over stdio.

Example Conversations

Targeted queries:

"Show me all my flagged tasks due this week"

"What are my next actions in the Work folder?"

"Count how many tasks are in each project"

Reorganizing:

"I want every task to have an energy level tag. Show me a list of all the tasks that don't have one and your suggestions for what tag to add. I'll make any changes I think are appropriate. Then make the changes in OmniFocus."

Capturing from anywhere:

"Ok, thanks for the detailed explanation of why the rule of law is important. Add a recurring task to my activism project that reminds me to call my representative weekly. Include a summary of this conversation in the notes field."

Working with perspectives:

"What perspectives do I have available?"

"Show me what's in my Inbox perspective"

Processing transcripts or PDFs:

"I'm pasting in the transcript from today's meeting. Please analyze it and create tasks in OmniFocus for any action items assigned to me. Put them in my 'Product Development' project."

Tools

The server provides 12 tools. Optional parameters are marked.

query_omnifocus

Query tasks, projects, or folders with targeted filters — much faster and lighter than dumping the whole database. See QUERY_TOOL_REFERENCE.md for the full reference and QUERY_TOOL_EXAMPLES.md for worked examples.

Available filters:

• Containers: projectName (case-insensitive partial match; "inbox" targets the inbox), projectId, folderId (includes subfolders), folderName (case-insensitive partial match, includes subfolders)
• Names: taskName (case-insensitive partial match)
• Tags: tags (exact match, case-sensitive)
• Status: status — tasks: Next, Available, Blocked, DueSoon, Overdue, Completed, Dropped; projects: Active, OnHold, Done, Dropped
• Dates, forward-looking: dueWithin, deferredUntil, plannedWithin (ranges), dueOn, deferOn, plannedOn (exact day). Accept a number of days, "today", "tomorrow", "this week", "next week", or an ISO date
• Dates, backward-looking: addedWithin, addedOn, completedWithin, completedOn, droppedWithin, droppedOn (same value forms; completed/dropped filters require includeCompleted: true)
• Flags & misc: flagged, inbox, hasNote, isRepeating (tasks only), reviewDue (projects only)

Filter names are not field names: the filter is inbox, the field is inInbox. Unknown filter keys are rejected, and so are filters or status values that don't apply to the queried entity (folders take only folderId, folderName and status). See the reference for per-entity applicability and exact date semantics.

dump_database

Get the complete state of your database. Use for comprehensive analysis; prefer query_omnifocus for anything targeted.

• hideCompleted (optional): hide completed/dropped tasks (default: true)
• hideRecurringDuplicates (optional): hide duplicate instances of recurring tasks (default: true)

add_omnifocus_task

Create a new task.

• name
• projectName (optional): project to add the task to (defaults to inbox)
• parentTaskId / parentTaskName (optional): nest under an existing task
• note, dueDate, deferDate, plannedDate, flagged, estimatedMinutes, tags (all optional)
• repeat (optional): make it recurring — see Repeating items

add_project

Create a new project.

• name
• folderName (optional): folder to place the project in
• sequential (optional): whether tasks must be completed in order
• note, dueDate, deferDate, flagged, estimatedMinutes, tags, repeat (all optional)

edit_item

Edit an existing task or project. Also the way to move items — set newProjectName to move a task into a project, or to ""/"inbox" to send it to the inbox.

• id or name: which item to edit (id takes precedence)
• itemType: task or project
• Common: newName, newNote, newDueDate, newDeferDate, newFlagged, newEstimatedMinutes (dates in ISO format; empty string clears)
• Tasks: newStatus (incomplete, completed, dropped, skipped — skipped only for repeating tasks), addTags, removeTags, replaceTags, newProjectName, newPlannedDate
• Tasks, nesting and order: newParentTaskId puts the task under another task (an action group), keeping its id and anything that links to it; "" returns it to the top level of its project, or of the inbox if it has no project. position places it among its siblings: "beginning", "end", {"before": "<id>"} or {"after": "<id>"}.
• Projects: newProjectStatus (active, completed, dropped, onHold), newFolderName, newSequential, newReviewInterval ({"steps": 2, "unit": "week"}; units day, week, month, year), markReviewed (sets the next review date based on the project's review interval, including one set in the same call)
• Repetition: newRepeat sets a new rule (same shape as repeat on create); newRepeat: null clears it

Rules for nesting and ordering:

• A task follows its parent. If the parent is in another project or in the inbox, the task moves there too.
• position without newParentTaskId reorders the task within its current parent.
• A before/after task must be a sibling under the target parent; otherwise the edit fails.
• Nesting a task under itself or one of its own subtasks fails, as does naming a project as the parent.
• newParentTaskId can't be combined with newProjectName (the parent decides the project). position can: the task is moved to the project, then placed.
• Both fields are for tasks only, and newReviewInterval is for projects only. Passing one on the wrong item type is an error, not a silent skip.
• The result names what was stored, e.g. parent (moved under Plan launch), position (after hZ3kP1x) or review interval (every 2 weeks). query_omnifocus reports the interval back in the same words (reviewInterval: "2 weeks").

At least one editable field is required — a call with only id/name/itemType is refused rather than reported as a successful no-op. Unrecognized argument keys (a note typo for newNote, say) are rejected by every tool with the key named in the error, instead of being silently dropped.

remove_item

Remove a task or project.

• id or name: which item to remove
• itemType: task or project

batch_add_items

Create multiple tasks and projects in one operation. Each item accepts the same fields as add_omnifocus_task / add_project, plus type (task or project) and optional hierarchy helpers:

• tempId: a temporary ID other items in the same batch can reference
• parentTempId: nest this item under another batch item's tempId

{
  "items": [
    { "type": "project", "name": "My Project", "tempId": "proj1" },
    { "type": "task", "name": "First task", "parentTempId": "proj1" },
    { "type": "task", "name": "Parent task", "parentTempId": "proj1", "tempId": "t1" },
    { "type": "task", "name": "Subtask", "parentTempId": "t1" }
  ]
}

batch_remove_items

Remove multiple tasks or projects in one operation. Each item takes id or name, plus itemType.

list_perspectives

List available perspectives, both built-in and custom (custom perspectives are an OmniFocus Pro feature).

• includeBuiltIn, includeCustom (optional, default: true)

get_perspective_view

Get the items visible in a named perspective.

• perspectiveName: e.g. Inbox, Flagged, or a custom perspective name
• limit (optional, default: 100), includeMetadata (optional), fields *(o