OmniFocus Enhanced

npm version License: MIT Node.js CI macOS

🌟 NEW: Native Custom Perspective Access with Hierarchical Display!

Transform OmniFocus into an AI-powered productivity powerhouse with custom perspective support

Enhanced Model Context Protocol (MCP) server for OmniFocus featuring native custom perspective access, hierarchical task display, AI-optimized tool selection, and comprehensive task management.

In plain English: this lets your AI assistant read your OmniFocus data, create tasks/projects, organize subtasks, review perspectives, and help you plan work without you manually jumping between apps.

🌠 Why This Project Exists

OmniFocus is already powerful, but it is still mostly a tool you drive by hand.

The bigger idea behind this project is simple:

• less clicking, more conversation
• less manual cleanup, more AI-assisted planning
• less tool memorization, more natural task management

The goal is not just to expose more OmniFocus commands. The goal is to let you work with OmniFocus like this:

Plan my day.
Clean up my Inbox.
Turn these notes into a project.
Show me what is blocked.
Reorganize these tasks safely.

If that feels natural, this MCP server is doing its job.

Want to see where the project is heading next? See the roadmap.

🆕 Latest Release

• v2.1.1 - Due, defer, and planned dates now keep their time of day. appleScriptDateCode hardcoded hours, minutes, and seconds to zero, so every date written through add_omnifocus_task, add_project, and edit_item collapsed to local midnight even though those tool schemas advertise a full ISO date. create_project_from_outline, which writes through JXA, had always preserved the time, so the two write paths disagreed. The time is now read straight from the ISO string exactly as the year, month, and day already were: verbatim wall-clock, with no timezone conversion, so an offset or Z suffix is ignored and the day can never drift away from the time it was paired with. Date-only input still resolves to midnight, so existing callers are unaffected. Thanks to @danilicari (#40).

  This build also carries the spaced-path installer fixes described under v2.1.0, which landed after that release was already published to npm.

• v2.1.0 - Custom perspective rule management: the new manage_perspectives tool reads, explains, and edits the filter rules behind a custom perspective, replacing list_custom_perspectives. Rules are exposed as a readable, name-based document instead of raw primary keys, and edits are written in place so a perspective's identifier never changes. The rule vocabulary was verified against the running app rather than taken from Omni's documentation, which proved both incomplete and partly wrong: actionHasPlannedDate is undocumented, the documented changed date field is ignored by the filter engine, and an entire actionHasDate* family present in the binary is dead. OmniFocus performs no validation on rule writes — an invalid rule is stored intact and then silently makes the perspective match everything — so the server validates every rule before writing, preserves rules it does not recognize verbatim, refuses unknown or ambiguous tag and project names, rolls back on failure, and forces the display refresh that OmniFocus otherwise skips. Creating and deleting perspectives remain out of scope: OmniFocus exposes no automation API for either. The surface remains 25 tools, 5 prompts, and 3 resources.

  The skill installer also stops leaking latency. mcporter only keeps an MCP server process alive when its config entry asks for it, and its built-in defaults cover a handful of browser-automation servers and nothing else, so every CLI call was re-resolving npx -y and cold starting a server. The installer now registers the server with lifecycle: "keep-alive" and asserts the setting reached the generated bundle — measured at 2.1x faster per command (12.9s → 6.1s median, interleaved A/B). Note that mcporter generate-cli --from <bundle> drops lifecycle from its replay metadata, so refreshing the CLI that way silently reverts this; install-skill is the only supported refresh path. The generated CLI is also pinned to --runtime node, because mcporter otherwise picks the runtime from whatever is on PATH at generation time and emits a #!/usr/bin/env bun shebang that fails to exec from shells with a narrower PATH. A new test asserts the installer's verification checklist names exactly the tools the server registers, so a renamed tool can no longer ship an installer that aborts on a correctly installed package.

  Installer verification now also quotes every generated CLI executable path. Project-local skills frequently live below directories such as Mobile Documents; the previous unquoted task-tree, outline, and repetition checks split those paths at spaces, swallowed the exec error with || true, and falsely reported that valid generated flags were missing. A regression test covers every verification invocation.

• v2.0.0 - Consolidated the MCP surface from 41 specialized tools to 25 strict tools: task views now use get_tasks, project reads use get_projects, and Folder/Tag/notification CRUD use manage_* actions. Removed legacy tool names rather than keeping aliases. Detailed task reads now preserve each assigned leaf tag while exposing its full OmniFocus hierarchy through path and ancestorIds (for example, 团队 / 守一); compact reads still omit tags. The bundled Skill and installer now generate and verify the 25-command surface.

• v1.21.0 - Batch task completion: new batch_complete_tasks tool marks up to 100 tasks complete or incomplete by stable ID in one verified transaction. The tool preflights every ID, snapshots original completion states, applies each action, reads back to verify status and completion dates, and restores previous states on any failure. Repeating tasks generate new instances when completed; the tool reports generatedTaskId and nextOccurrence. Idempotent items are reported as unchanged rather than failing. The surface now includes 41 tools, 5 prompts, and 3 resources.

• v1.20.0 - Repeating tasks completed: repetition is now readable and verified everywhere. get_task_by_id returns the rule string, schedule type, anchor date, catch-up behavior, and the next occurrence; list reads add only an isRepeating marker; dump_database reports real repetition instead of hard-coded nulls. add_omnifocus_task and every task node of create_project_from_outline accept a repetition object using ICS rule strings, and set_repetition_rule now snapshots the previous rule, verifies every written field, restores on failure, and reports an unconfirmed restore with the affected task ID. The surface remains 40 tools, 5 prompts, and 3 resources.

• v1.19.0 - Project Shaping: added create_project_from_outline for turning one user-confirmed structured outline into a complete OmniFocus project tree. The tool accepts stable Folder/Tag IDs and core planning fields, enforces a 200-task/eight-level bound, preflights every reference before writing, creates the tree in one OmniJS request, reads every node and field back, and performs one bounded Undo if execution or verification fails. The new project_shaping Prompt and bundled Skill guide extract, disclose inferences, resolve IDs, confirm, create, and report. The surface is now 40 tools, 5 prompts, and 3 resources.

• v1.18.0 - Reliability release: upgraded the MCP SDK to 1.30.0 and Zod to 3.25.76; migrated Resources to registerResource with bounded task snapshots that distinguish totalCount, returnedCount, and truncation; restored the user's original OmniFocus perspective after custom-perspective reads; removed the unused incomplete Perspective V2/debug implementation; and rebuilt batch_remove_items around stable IDs, complete preflight, undo-based rollback on execution failure, cascade reporting, and post-delete verification.

• v1.17.1 - Maintenance release: migrated all 39 tools and 4 prompts to the current MCP registration APIs with read/additive/destructive annotations, restored mandatory strict TypeScript checking, raised the runtime baseline to Node.js 22, and reduced the npm tarball from about 2.27 MB to about 117 KB by publishing only runtime artifacts. The repository logo is now 512×341 and about 175 KB instead of 1.97 MB.

• v1.17.0 - Filter pagination and query efficiency: filter_tasks now returns stateless opaque keyset cursors for real-time best-effort traversal, with stable ID tie-breaking and strict query/sort validation. Compact reads omit notes and tags inside OmniJS, normal list reads skip unused status aggregation, and later pages use cursor boundaries plus one-item lookahead. The privacy-safe benchmark now records first- and second-page metrics. The surface remains 39 tools, 4 prompts, and 3 resources.

• v1.16.0 - Daily Planning Assistant: daily_review now uses exact count-first discovery and bounded, deduplicated candidates to produce three priorities plus next actions, blockers, and capacity/deadline risks. Its optional availableMinutes input compares only known estimates and preserves missing estimates as uncertainty. filter_tasks adds opt-in compact output for broad planning reads without notes or full tags, and a privacy-safe local benchmark provides numeric regression evidence. The surface remains 39 tools, 4 prompts, and 3 resources.

• v1.15.0 - Weekly Review completion: added the narrow mark_projects_reviewed tool for marking a user-confirmed set of active or on-hold projects reviewed. The server validates every project and its review metadata before writing, uses one timestamp for the complete batch, restores prior review dates after execution or verification failures, and verifies lastReviewDate, the OmniFocus-generated nextReviewDate, and the unchanged review interval. The Weekly Review Prompt and Skill now guide discovery, discussion, confirmation, marking, and remaining-review reporting. Now 39 tools, 4 prompts, and 3 resources.

• v1.14.0 - Safe Inbox organization: added the intentionally narrow batch_move_tasks tool for executing a user-confirmed move proposal using stable task and destination IDs. The server preflights the complete batch before changing anything, blocks invalid destinations and hierarchy cycles, rolls back completed moves after execution failures, and verifies every final destination. The inbox_processing Prompt and bundled Skill now guide AI clients through read, propose, confirm, execute, and report. Now 38 tools, 4 prompts, and 3 resources.

• v1.13.1 - Maintenance release: MCP server metadata now reads its version from package.json, preventing the MCP handshake, CLI, NPM package, and GitHub release versions from drifting apart. The published Skill installation was also verified end to end with all 37 commands, all six task-tree flag pairs, and a live OmniFocus connection.

• v1.13.0 - Task-tree-aware reads: get_inbox_tasks, get_flagged_tasks, get_forecast_tasks, get_tasks_by_tag, filter_tasks, and get_task_by_id now show visible direct subtask counts by default and support on-demand recursive expansion with showSubtasks and maxSubtaskDepth. Expanded lists suppress duplicate top-level descendants, inherit completion visibility rules, and enforce a 500-node safety cap with explicit truncation output. The bundled omnifocus-cli Skill documents the new workflow and verifies both generated CLI flags during installation.

• v1.12.0 - Reliability release: rebuilt filter_tasks and count_tasks on one complete OmniJS predicate (due/defer/planned/completion dates, estimates, notes, tags, inbox, project, status, and combined filters now actually work); added low-overhead countOnly aggregation; added get_projects and get_projects_due_for_review with native OmniFocus review metadata; upgraded the MCP SDK to 1.29.0 and cleared all production audit findings; updated the Claude skill to 37 tools and changed its generated bundle to .cjs so project-local installs work inside ESM repositories.

• v1.11.1 - Fixed skill installation scope for Claude Code: install-skill now installs into the current project's .claude/skills/omnifocus-cli/ and writes a project-scoped mcporter config by default. Pass --global to opt into ~/.claude/skills/omnifocus-cli/ and the home mcporter config. CLAUDE_SKILLS_DIR can override the skill root.

• v1.11.0 - Added a bundled agent skill (omnifocus-cli). One command (npx omnifocus-mcp-enhanced install-skill) generates a local CLI covering all 35 tools, so AI agents can drive OmniFocus through shell commands instead of loading 35 tool schemas into context. The CLI is generated on your machine from your installed server version, so it never drifts out of sync.

• v1.10.0 - Major capability expansion: Tag Management (add_tag, edit_tag, remove_tag, search_tags), Task Notifications (list_task_notifications, add_task_notification, remove_task_notification — absolute or due-relative reminders), plus first-class MCP Prompts (4 guided review workflows) and Resources (3 live JSON snapshots). Now 35 tools, 4 prompts, and 3 resources.

• v1.9.0 - Added 3 productivity tools: append_to_note (append text to a task/project note without overwriting), count_tasks (fast "how many" aggregate queries with a status breakdown, using the same filters as filter_tasks), and duplicate_task (clone a task with or without its subtasks, optionally renamed).

• v1.8.0 - Added full Folder Management support: add_folder, edit_folder, remove_folder, list_folders, and get_folder. Create nested folder hierarchies, rename/move folders (with cycle protection), and inspect folder contents (child projects + subfolders). Note: removing a folder permanently deletes all projects and tasks it contains.

• v1.7.0 - Added OmniFocus 4.7+ repeat rule support via set_repetition_rule (ICS rule strings, schedule type, anchor date, catch-up, end date, repetition count), mutually exclusive tag support via exclusiveTags on add/edit tools, and improved planned-date editing tests.

• v1.6.10 - Fixed Inbox task completion via edit_item, fixed AppleScript special-character handling for apostrophes/backslashes, fixed JSON result escaping for special characters, and clarified batch_add_items / mcporter usage with working examples.

• v1.6.9 - Added task attachment support: get_task_by_id now lists attachment metadata, dump_database exports attachment/link metadata, and new read_task_attachment returns image attachments as MCP image content when possible.

• v1.6.8 - Added stable task move support via move_task and edit_item (newProjectId/newProjectName/newParentTaskId/newParentTaskName/moveToInbox) with duplicate-name protection and cycle-prevention checks.

• v1.6.6 - Added full Planned Date support (create/edit/read/filter/sort/export), including plannedDate/newPlannedDate and updated task displays.

✨ Key Features

🌟 NEW: Native Custom Perspective Access

• 🎯 Direct Integration - Native access to your OmniFocus custom perspectives via Perspective.Custom API
• 🌳 Hierarchical Display - Tree-style task visualization with parent-child relationships
• 🧠 AI-Optimized - Enhanced tool descriptions prevent AI confusion between perspectives and tags
• ⚡ Zero Setup - Works with your existing custom perspectives instantly

🏗️ Complete Task Management

• 🏗️ Complete Subtask Support - Create hierarchical tasks with parent-child relationships
• 🔍 Built-in Perspectives - Access Inbox, Flagged, Forecast, and Tag-based views
• 🚀 Ultimate Task Filter - Advanced filtering beyond OmniFocus native capabilities
• 🎯 Batch Operations - Add/remove multiple tasks efficiently
• 📊 Smart Querying - Find tasks by ID, name, or complex criteria
• 🔄 Full CRUD Operations - Create, read, update, delete tasks and projects
• 📁 Folder Management - Full CRUD for folders with nested hierarchy, move/rename, and content inspection
• 🏷️ Tag Management - Full CRUD for tags with nesting, status control, and fuzzy search
• 🔔 Task Notifications - List, add, and remove reminders (absolute time or relative to due date)
• 💬 MCP Prompts - 5 guided workflows (daily, weekly, inbox processing, project planning, project shaping)
• 📡 MCP Resources - 3 live JSON snapshots (inbox, today, active projects)
• 🛠️ Agent Skill - One-command install of a local CLI covering all 25 consolidated tools, to keep AI context usage low
• 📅 Time Management - Due, defer, planned dates, estimates, and scheduling
• 🏷️ Advanced Tagging - Tag-based filtering with exact/partial matching
• 🚫 Mutually Exclusive Tags - Automatically respects exclusive tag groups when applying tags
• 🔁 Repeat Rules - Full OmniFocus 4.7+ repetition support (ICS rules, schedule type, anchor date, catch-up, end date, count)
• 🤖 AI Integration - Seamless Claude AI integration for intelligent workflows
• 🖼️ Attachment-Aware Reads - Surface note attachments and linked files before deciding whether AI should inspect them

📦 Installation

Claude Code

Quick Install (recommended)

# One-line installation
claude mcp add omnifocus-enhanced -- npx -y omnifocus-mcp-enhanced

Alternative methods for Claude Code:

# Upgrade to latest
npm install -g omnifocus-mcp-enhanced@latest

# Global installation
npm install -g omnifocus-mcp-enhanced
claude mcp add omnifocus-enhanced -- omnifocus-mcp-enhanced

# Local project installation (project-scoped)
# This creates/updates the current project's .mcp.json so the server is only available here.
git clone https://github.com/jqlts1/omnifocus-mcp-enhanced.git
cd omnifocus-mcp-enhanced
npm install && npm run build
claude mcp add -s project omnifocus-enhanced -- node "/path/to/omnifocus-mcp-enhanced/dist/server.js"

You can also install from npm into the consuming project's devDependencies instead of cloning:

npm install --save-dev omnifocus-mcp-enhanced
claude mcp add -s project omnifocus-enhanced -- npx -y omnifocus-mcp-enhanced

After adding, run claude once in the project directory and approve the pending MCP connection.

Claude Desktop / Cowork

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

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

For a local clone, use:

{
  "mcpServers": {
    "omnifocus-enhanced": {
      "command": "node",
      "args": ["/path/to/omnifocus-mcp-enhanced/dist/server.js"]
    }
  }
}

Restart Claude Desktop after editing the config file.

Using Both Claude Code and Claude Desktop / Cowork

Claude Code and Claude Desktop read separate configurations. If you want to use this MCP server from both, you need to install it in both places — run claude mcp add for Claude Code and add the entry to claude_desktop_config.json for Claude Desktop / Cowork.

📋 Requirements

• macOS 10.15+ - OmniFocus is macOS-only
• OmniFocus 3+ - The application must be installed and running
• OmniFocus Pro - Required for custom perspectives (new features in v1.6.0)
• Node.js 18+ - For running the MCP server
• Any MCP-capable client - Claude Code, mcporter, or another MCP host

🚦 Start Here

If you only want the fastest way to understand this project, remember this:

1. Connect the MCP server to your AI client.
2. Talk to the AI naturally.
3. Let it read, plan, create, move, or update your OmniFocus tasks for you.

You do not need to memorize all tool names first.

🙋 What This Is Good For

• Daily planning: ask your AI what is due today, what is flagged, and what you can finish in 30 minutes.
• Project setup: give the AI a rough goal, then let it create a project and break it into subtasks.
• Inbox cleanup: ask it to review Inbox tasks and sort them into next actions, projects, or someday/later buckets.
• Perspective reviews: ask it to open one of your custom perspectives and summarize what matters.
• Batch capture: paste meeting notes or a brainstorm list and let the AI create multiple tasks at once.
• Attachment-aware review: let the AI inspect task attachments only when needed.

💬 Example AI Conversations

These work well in Claude Code or any MCP client that can call the same tools.

1. Daily Planning

Try saying:

Check my Forecast and flagged tasks, then tell me the 3 most important things to do today.
Prefer tasks that take under 60 minutes first.

2. Inbox Cleanup

Try saying:

Review my Inbox and group the tasks into:
1. do today
2. schedule later
3. turn into projects
Then help me clean up the obvious ones.

3. Turn an Idea Into a Project

Try saying:

Create a project called "Launch spring newsletter".
Add the main subtasks, estimated minutes, and mark the most important step as flagged.

4. Use a Custom Perspective

Try saying:

Open my custom perspective "今日工作安排" and summarize:
- what is due soon
- what looks blocked
- what I can finish quickly

5. Batch Add From Notes

Try saying:

Turn these meeting notes into OmniFocus tasks under the project "Website Refresh".
Use subtasks where it makes sense and keep the task names short.

6. Review Attachments Only When Needed

Try saying:

Find the task called "Review design draft".
Show me what attachments it has first.
Only open the image attachment if there is one.

🧭 Practical Usage Tips

• Ask the AI to look first, then change things if you want safer workflows.
• Use task IDs when you have duplicate task names.
• For subtasks, let the parent task determine the project. Do not also pass projectName.
• For mcporter, complex arrays are much more reliable with --args '{...}'.

🎯 Core Capabilities

1. 🏗️ Subtask Management

Create complex task hierarchies with ease:

// Create subtask by parent task name
{
  "name": "Analyze competitor keywords",
  "parentTaskName": "SEO Strategy",
  "note": "Focus on top 10 competitors",
  "dueDate": "2025-01-15",
  "estimatedMinutes": 120,
  "tags": ["SEO", "Research"]
}

// Create subtask by parent task ID
{
  "name": "Write content outline",
  "parentTaskId": "loK2xEAY4H1",
  "flagged": true,
  "estimatedMinutes": 60
}

2. 🔍 Perspective Views

Access all major OmniFocus perspectives programmatically:

# Inbox perspective
get_tasks {"source": "inbox", "hideCompleted": true}

# Flagged tasks
get_tasks {"source": "flagged", "projectFilter": "SEO Project"}

# Forecast (next 7 days)
get_tasks {"source": "forecast", "days": 7, "hideCompleted": true}

# Tasks by tag
get_tasks {"source": "tag", "tagName": "AI", "exactMatch": false}

# Every result shows its direct subtask count; expand the task tree on demand
get_tasks {"source": "inbox", "showSubtasks": true, "maxSubtaskDepth": 2}

showSubtasks defaults to false. maxSubtaskDepth is a non-negative integer: 0 expands nothing, 1 shows direct children, and omitting it allows full recursion. List commands apply their completed-task visibility to descendants. Expanded descendants provide structure and do not need to match the top-level filter themselves.

Detailed task reads preserve the assigned leaf tag and show its full hierarchy path. For example, a task assigned 守一 under 团队 is rendered as 团队 / 守一; structured results retain the leaf id/name and add path plus ancestorIds. Compact output continues to omit tags.

3. 🚀 Ultimate Task Filter

Create any perspective imaginable with advanced filtering:

# Time management view (30min tasks due this week)
filter_tasks {
  "taskStatus": ["Available", "Next"],
  "estimateMax": 30,
  "dueThisWeek": true
}

# Deep work view (60+ minute tasks with notes)
filter_tasks {
  "estimateMin": 60,
  "hasNote": true,
  "taskStatus": ["Available"]
}

# Planned work view (tasks planned for today)
filter_tasks {
  "plannedToday": true,
  "sortBy": "plannedDate"
}

# Project overdue tasks
filter_tasks {
  "projectFilter": "Website Redesign",
  "taskStatus": ["Overdue", "DueSoon"]
}

# Keep the same matching rules, but include two levels of task structure
filter_tasks {
  "flagged": true,
  "showSubtasks": true,
  "maxSubtaskDepth": 2
}

# Compact broad discovery for planning (omits notes and full tags)
filter_tasks {
  "plannedToday": true,
  "limit": 30,
  "outputMode": "compact"
}

daily_review is the one-step daily-planning Prompt. Optionally provide availableMinutes; when omitted, it does not assume an eight-hour day. It starts with exact counts, reads bounded candidates, selects exactly three priorities when possible, and returns 今日重点, 可执行下一步, 阻塞项, and 容量/截止风险. Any proposed OmniFocus changes are grouped into one confirmation request.

When a filtered result has more tasks, filter_tasks returns an opaque next cursor. Pass it back with the same filters and sorting:

{
  "flagged": true,
  "limit": 30,
  "sortBy": "dueDate",
  "outputMode": "compact",
  "cursor": "<next cursor>"
}

Changing filters or sorting invalidates the cursor. limit, outputMode, and task-tree rendering may change between pages. Each page reads current OmniFocus state, so pagination is real-time best effort rather than a snapshot.

4. 🌟 NEW: Native Custom Perspective Access

Access your OmniFocus custom perspectives with hierarchical task display:

# List all your custom perspectives
manage_perspectives {"action": "list"}

# Read a perspective's filter rules, explained in plain language
manage_perspectives {"action": "get", "name": "今日工作安排"}

# 🌳 NEW: Project tree view (default)
get_tasks {
  "source": "custom",
  "perspectiveName": "今日工作安排",  # Your custom perspective name
  "displayMode": "project_tree",    # project_tree | task_tree | flat
  "hideCompleted": true
}

# Global task tree (legacy showHierarchy=true equivalent)
get_tasks {
  "source": "custom",
  "perspectiveName": "Today Review",
  "displayMode": "task_tree"
}

# Flat list (legacy groupByProject=false equivalent)
get_tasks {
  "source": "custom",
  "perspectiveName": "Weekly Planning",
  "displayMode": "flat"
}

Why This Is Powerful:

• ✅ Native Integration - Uses OmniFocus Perspective.Custom API directly
• ✅ Tree Structure - Visual parent-child task relationships with ├─, └─ symbols
• ✅ Project-First Grouping - Project header first, then nested subtasks
• ✅ Readable Metadata - Detailed task reads show full notes and hierarchical tag paths such as #Team / Member; compact reads still omit tags
• ✅ AI-Friendly - Enhanced descriptions prevent tool selection confusion
• ✅ Professional Output - Clean, readable task hierarchies

5. 🎯 Batch Operations

Efficiently manage multiple tasks:

{
  "items": [
    {
      "type": "task",
      "name": "Website Technical SEO",
      "projectName": "SEO Project",
      "note": "Optimize technical aspects"
    },
    {
      "type": "task",
      "name": "Page Speed Optimization",
      "parentTaskName": "Website Technical SEO",
      "estimatedMinutes": 180,
      "flagged": true
    },
    {
      "type": "task",
      "name": "Mobile Responsiveness",
      "parentTaskName": "Website Technical SEO",
      "estimatedMinutes": 90
    }
  ]
}

CLI tip for mcporter:

# Prefer explicit JSON args for complex arrays / nested objects
mcporter call omnifocus.batch_add_items --args '{
  "items": [
    {
      "type": "task",
      "name": "Website Technical SEO",
      "projectName": "SEO Project"
    }
  ]
}'

If you pass a subtask with parentTaskId or parentTaskName, do not also pass projectName. Subtasks inherit the project from their parent task.

Working mcporter examples:

# 1) Batch-create top-level tasks in a project
mcporter call omnifocus.batch_add_items --args '{
  "items": [
    {
      "type": "task",
      "name": "Parent: Category A",
      "projectName": "OmniFocus MCP Batch Test"
    },
    {
      "type": "task",
      "name": "Parent: Category B",
      "projectName": "OmniFocus MCP Batch Test"
    }
  ]
}'

# 2) Create parent + child in one batch
mcporter call omnifocus.batch_add_items --args '{
  "items": [
    {
      "type": "task",
      "name": "Parent: Category A",
      "projectName": "OmniFocus MCP Batch Test"
    },
    {
      "type": "task",
      "name": "Child: A1",
      "parentTaskName": "Parent: Category A"
    }
  ]
}'

# 3) Safer two-step flow when adding many subtasks to existing parents
mcporter call omnifocus.batch_add_items --args '{
  "items": [
    {
      "type": "task",
      "name": "Child: A1",
      "parentTaskName": "Parent: Category A"
    },
    {
      "type": "task",
      "name": "Child: A2",
      "parentTaskName": "Parent: Category A"
    },
    {
      "type": "task",
      "name": "Child: B1",
      "parentTaskName": "Parent: Category B"
    }
  ]
}'

This will fail, by design:

mcporter call omnifocus.batch_add_items --args '{
  "items": [
    {
      "type": "task",
      "name": "Child: A1",
      "projectName": "OmniFocus MCP Batch Test",
      "parentTaskName": "Parent: Category A"
    }
  ]
}'

Because a subtask must inherit its project from the parent task.

6. Project Shaping

Use project_shaping to turn meeting notes, brainstorming, or a task list into a readable project tree. The assistant labels inferred metadata, resolves Folder and Tag stable IDs, and asks for explicit confirmation of the final tree before calling create_project_from_outline once.

{
  "project": {
    "name": "Website launch",
    "folderId": "folder-id",
    "tagIds": ["tag-id"],
    "sequential": true,
    "tasks": [
      {
        "name": "Confirm information architecture",
        "estimatedMinutes": 60,
        "children": [{ "name": "Review navigation" }]
      }
    ]
  }
}

The action accepts structured, reviewed fields—not raw meeting notes. It supports at most 200 tasks and eight task levels. Missing references cause zero writes. Execution or read-back failure triggers one bounded OmniFocus Undo; if cleanup cannot be confirmed, the error includes the residual project ID.

7. Repeating Tasks

Repetition is a first-class field. Create it, read it, change it, and clear it—all verified.

{
  "name": "Weekly admin checklist",
  "repetition": {
    "ruleString": "FREQ=WEEKLY;BYDAY=FR",
    "scheduleType": "Regularly",
    "anchorDateKey": "DueDate",
    "catchUpAutomatically": true
  }
}

• add_omnifocus_task and task nodes of create_project_from_outline accept the same object. UNTIL and COUNT belong inside ruleString; the deprecated method parameter is never exposed.
• get_task_by_id reports the stored rule plus the next occurrence. List reads add only isRepeating, so broad queries stay small.
• set_repetition_rule verifies the saved rule field by field. A failed write or mismatch restores the previous rule; if restoration cannot be confirmed, the error names the task that needs manual review.
• A verification failure during creation removes the task, or rolls back the whole project tree, so no item keeps a recurrence the user did not confirm.

8. 🖼️ Attachment Inspection

Discover images and linked files on a task first, then read only the attachment you need:

# List task details plus attachment metadata
get_task_by_id {
  "taskId": "abc123"
}

# Open an attachment returned by get_task_by_id
read_task_attachment {
  "taskId": "abc123",
  "attachmentId": "embedded-1"
}

get_task_by_id now reports attachment IDs, names, MIME guesses, source (embedded vs linked), and sizes when available. read_task_attachment returns images as MCP image content when possible, so AI clients can inspect the image directly instead of parsing base64 from plain text.

🛠️ Complete Tool Reference — 25 Tools

Task and project operations

1. dump_database - Export the OmniFocus database
2. add_omnifocus_task - Create one task, including subtasks and repetition
3. add_project - Create one project
4. remove_item - Delete a task or project
5. edit_item - Edit or reposition a task or project
6. move_task - Move one task
7. batch_move_tasks - Atomically move a confirmed task set
8. batch_complete_tasks - Atomically complete or reopen up to 100 tasks
9. batch_add_items - Add multiple tasks or projects
10. batch_remove_items - Atomically delete a confirmed item set
11. create_project_from_outline - Create and verify one complete project tree
12. get_task_by_id - Read one task and its attachment metadata
13. read_task_attachment - Read one reported task attachment
14. get_tasks - Read inbox, flagged, forecast, tag, or custom-perspective tasks via source
15. filter_tasks - Filter tasks by status, dates, project, tags, text, and more; use { "completedToday": true } for today's completed work
16. get_projects - Read all projects or use view=due_for_review for projects due for review
17. mark_projects_reviewed - Atomically mark confirmed projects reviewed
18. set_repetition_rule - Set, update, or clear a task repeat rule

Organization and productivity

19. manage_perspectives - list, get, or update custom perspectives and their filter rules
20. manage_folders - list, get, add, edit, or remove folders
21. manage_tags - list, search, add, edit, or remove tags
22. manage_task_notifications - list, add, or remove task reminders
23. append_to_note - Append without overwriting a task/project note
24. count_tasks - Count tasks using the filter engine
25. duplicate_task - Duplicate a task, optionally with subtasks

The four manage_* tools mix reads and writes, so their MCP annotations are deliberately conservative and destructive. list/get/search actions do not mutate; remove actions require the same confirmation discipline as dedicated deletion tools. manage_perspectives never creates or deletes a perspective — OmniFocus exposes no automation API for either — so its only write is an in-place edit.

💬 MCP Prompts (NEW in v1.10.0)

Guided review workflows that pull live OmniFocus data and hand the AI a structured plan of attack. In clients like Claude Desktop these appear as selectable prompts.

Prompt	Arguments	What it does
daily_review	–	Pulls overdue, due-soon, and flagged tasks; produces today's top 3 priorities
weekly_review	–	GTD weekly review: classifies active projects as on track / at risk / stalled, proposes next actions
inbox_processing	–	Walks inbox items one by one through GTD clarification (delete/defer/delegate/keep)
project_planning	project	Breaks a project into sequenced, estimated next actions (fuzzy-matches the project name)
project_shaping	–	Turns conversation text into one reviewed, confirmed, verified project tree

📡 MCP Resources (NEW in v1.10.0)

Live JSON snapshots your AI client can read without calling a tool.

Resource URI	Contents
omnifocus://inbox	Current inbox tasks
omnifocus://today	Overdue + due today + flagged, grouped
omnifocus://projects	Active projects with task counts and stalled detection

🛠️ Agent Skill (NEW in v1.11.0)

With 25 consolidated tools, loading every MCP schema still costs context. The bundled omnifocus-cli skill generates a local CLI so agents can drive OmniFocus through compact shell commands instead.

Install

npx -y omnifocus-mcp-enhanced@latest install-skill

By default, this installs only in the current project:

your-project/
├── .claude/skills/omnifocus-cli/
│   ├── SKILL.md
│   └── bin/omnifocus-enhanced.cjs
└── config/mcporter.json

Use --global only when you intentionally want the skill available in every project:

npx -y omnifocus-mcp-enhanced@latest install-skill --global

The global skill is installed in ~/.claude/skills/omnifocus-cli/, and its MCP server registration is written to the home mcporter configuration.

That single command:

1. Registers the MCP server with mcporter, pinned to the exact package version that shipped the installer, with lifecycle: "keep-alive" so repeat calls reuse one warm server instead of cold starting one each time
2. Generates a standalone CLI from the server's live tool schemas (~20s), pinned to the Node runtime so the CLI stays runnable from any shell
3. Installs SKILL.md + the CLI into the current project's .claude/skills/omnifocus-cli/ (or ~/.claude/skills/omnifocus-cli/ with --global)
4. Verifies all 25 tools are present, that keep-alive reached the generated bundle, and that OmniFocus is reachable

Install elsewhere with CLAUDE_SKILLS_DIR=/custom/path npx -y omnifocus-mcp-enhanced@latest install-skill (AGENT_SKILLS_DIR remains available as a legacy alias).

Why generate the CLI locally?

The CLI is not shipped pre-built. It is generated on your machine from the server version you actually have installed, which means it can never silently lack the newest commands — the most common failure mode for this kind of tooling.

Usage

CLI=.claude/skills/omnifocus-cli/bin/omnifocus-enhanced.cjs

$CLI get-tasks --source inbox
$CLI count-tasks --flagged true
$CLI filter-tasks --task-status Available,Next --due-this-week true
$CLI manage-folders --action add --name "Clients" --parent-folder-name "Work"

Flag conventions: booleans need explicit values (--flagged true), arrays are comma-separated (--task-status Available,Next), and --raw '<json>' bypasses flag parsing for complex nested arguments.

Keeping it current

Re-run the installer after upgrading the server — a stale CLI will silently miss new tools:

npm install -g omnifocus-mcp-enhanced@latest
npx -y omnifocus-mcp-enhanced@latest install-skill

install-skill is the only supported refresh path. Do not use mcporter generate-cli --from <bundle>, even though mcporter inspect-cli suggests it: the replay metadata drops the server's lifecycle, so regenerating that way silently disables keep-alive and roughly doubles the latency of every command.

The keep-alive daemon runs against the generated CLI's own config, so a plain mcporter daemon status reads the wrong file and always reports "not running". Inspect the real one with:

npx -y mcporter@latest --config $(ls -t ~/.mcporter/generated/*.json | head -1) daemon status

Batch move feature roadmap (future): docs/roadmap/2026-02-25-batch-move-tasks-plan.md

🚀 Quick Start Examples

Basic Task Creation

# Simple task
add_omnifocus_task {
  "name": "Review quarterly goals",
  "projectName": "Planning",
  "dueDate": "2025-01-31",
  "plannedDate": "2025-01-28"
}

Advanced Task Management

# Create parent task
add_omnifocus_task {
  "name": "Launch Product Campaign",
  "projectName": "Marketing",
  "dueDate": "2025-02-15",
  "tags": ["Campaign", "Priority"]
}

# Add subtasks
add_omnifocus_task {
  "name": "Design landing page",
  "parentTaskName": "Launch Product Campaign",
  "estimatedMinutes": 240,
  "flagged": true
}

Task Move Operations

# Move task to a project
move_task {
  "id": "task-id-123",
  "targetProjectName": "Planning"
}

# Move task under another task
move_task {
  "id": "task-id-123",
  "targetParentTaskId": "parent-task-id-456"
}

# Move task back to inbox
move_task {
  "id": "task-id-123",
  "targetInbox": true
}

# Execute a user-confirmed organization plan as one atomic batch
batch_move_tasks {
  "moves": [
    { "taskId": "task-1", "projectId": "project-1" },
    { "taskId": "task-2", "parentTaskId": "parent-task-1" }
  ]
}

Task move safety rules:

• Name lookups fail fast on duplicates and ask you to use IDs.
• Destination must be exactly one type: project OR parent task OR inbox.
• Moving a task into itself/its descendants is blocked to prevent cycles.
• batch_move_tasks accepts stable IDs only, validates the complete plan before changing anything, and verifies every final destination.
• If batch preflight fails, no task is moved. Call it only after the user confirms the displayed organization proposal.

You can also move with edit_item and combine move + field updates:

edit_item {
  "itemType": "task",
  "id": "task-id-123",
  "newProjectName": "Planning",
  "newName": "Review tmux workflow",
  "newFlagged": true
}

Smart Task Discovery

# Find high-priority work
filter_tasks {
  "flagged": true,
  "taskStatus": ["Available"],
  "estimateMax": 120,
  "hasEstimate": true
}

# Today's completed work
filter_tasks {
  "completedToday": true,
  "taskStatus": ["Completed"],
  "sortBy": "project"
}

🌟 Custom Perspective Usage

# List your custom perspectives
manage_perspectives {"action": "list"}

# Access a custom perspective with project tree
get_tasks {
  "source": "custom",
  "perspectiveName": "Today Review",
  "displayMode": "project_tree",
  "hideCompleted": true
}

# Quick flat view of weekly planning
get_tasks {
  "source": "custom",
  "perspectiveName": "Weekly Planning",
  "displayMode": "flat"
}

📁 Folder Management

# List all folders with project counts
manage_folders {"action": "list", "includeDropped": false}

# Create a top-level folder
manage_folders {"action": "add", "name": "Work"}

# Create a nested folder
manage_folders {"action": "add", "name": "Clients", "parentFolderName": "Work"}

# Inspect a folder's projects and subfolders
manage_folders {"action": "get", "name": "Work"}

# Rename or move a folder (empty string moves to root)
manage_folders {"action": "edit", "name": "Clients", "newName": "Key Clients"}
manage_folders {"action": "edit", "name": "Key Clients", "newParentFolderName": ""}

# Delete a folder (⚠️ also deletes all contained projects and tasks)
manage_folders {"action": "remove", "name": "Old Archive"}

⚡ Productivity Tools

# Append a progress note without overwriting the existing note
append_to_note {
  "itemType": "task",
  "name": "Write report",
  "text": "Drafted section 1 today"
}

# Fast count: how many flagged tasks are still actionable?
count_tasks {
  "flagged": true,
  "taskStatus": ["Available", "Next", "DueSoon", "Overdue"]
}

# How many tasks remain in a project (by status breakdown)
count_tasks {"projectFilter": "Website Redesign"}

# Duplicate a task template with its subtasks
duplicate_task {
  "name": "Weekly Review Checklist",
  "newName": "Weekly Review - 2026-03-02"
}

# Duplicate without subtasks
duplicate_task {"taskId": "abc123", "includeSubtasks": false}

🏷️ Tag Management

# Search and list tags
manage_tags {"action": "search", "query": "work"}
manage_tags {"action": "list", "includeInactive": false}

# Create a tag, optionally nested
manage_tags {"action": "add", "name": "Deep Work"}
manage_tags {"action": "add", "name": "Client A", "parentTagName": "Clients"}

# Rename, pause, or move a tag ("" moves to root)
manage_tags {"action": "edit", "name": "Deep Work", "newName": "Focus"}
manage_tags {"action": "edit", "name": "Focus", "newStatus": "onHold"}
manage_tags {"action": "edit", "name": "Client A", "newParentTagName": ""}

# Delete a tag (tasks are kept, they just lose the tag)
manage_tags {"action": "remove", "name": "Obsolete"}

🔔 Task Notifications

# See what reminders a task has
manage_task_notifications {"action": "list", "taskName": "Submit report"}

# Remind at a fixed time
manage_task_notifications {
  "action": "add",
  "taskName": "Submit report",
  "absoluteDate": "2026-03-05T09:00:00"
}

# Remind 30 minutes before the due date (requires a due date)
manage_task_notifications {
  "action": "add",
  "taskName": "Submit report",
  "relativeMinutes": -30
}

# Remove one by index, or clear them all
manage_task_notifications {"action": "remove", "taskName": "Submit report", "index": 0}
manage_task_notifications {"action": "remove", "taskName": "Submit report", "removeAll": true}

🔧 Configuration

Claude Code

Verify the server is registered:

# Check MCP status
claude mcp list

# Test basic connection
get_tasks {"source": "inbox"}

# Test custom perspective access
manage_perspectives {"action": "list"}

Claude Desktop / Cowork

Open ~/Library/Application Support/Claude/claude_desktop_config.json and confirm the omnifocus-enhanced entry is present under mcpServers. Restart the app after any changes. Once running, you can test by asking the assistant to list your inbox tasks or custom perspectives.

Troubleshooting

• Ensure OmniFocus 3+ is installed and running
• Verify Node.js 18+ is installed
• For Claude Code: run claude mcp list to confirm the server is registered
• For Claude Desktop / Cowork: verify claude_desktop_config.json is valid JSON and restart the app
• Enable accessibility permissions for terminal apps if needed

🎯 Use Cases

• Project Management - Create detailed project hierarchies with subtasks
• GTD Workflow - Leverage perspectives for Getting Things Done methodology
• Time Blocking - Filter by estimated time for schedule planning
• Review Process - Use custom perspectives for weekly/monthly reviews
• Team Coordination - Batch operations for team task assignment
• AI-Powered Planning - Let Claude analyze and organize your tasks

📈 Performance

• Fast Filtering - Native AppleScript performance
• Batch Efficiency - Single operation for multiple tasks
• Memory Optimized - Minimal resource usage
• Scalable - Handles large task databases efficiently

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• NPM Package: https://www.npmjs.com/package/omnifocus-mcp-enhanced
• GitHub Repository: https://github.com/jqlts1/omnifocus-mcp-enhanced
• OmniFocus: https://www.omnigroup.com/omnifocus/
• Model Context Protocol: https://modelcontextprotocol.io/
• Claude Code: https://docs.anthropic.com/en/docs/claude-code

🙏 Acknowledgments

Based on the original OmniFocus MCP server by themotionmachine. Enhanced with perspective views, advanced filtering, and complete subtask support.

---

⭐ Star this repo if it helps boost your productivity!