Omnifocus MCP

Cleanup Review

python scripts/_reset_state.py is an optional cleanup helper for the Manage OmniFocus skill. It may recursively remove /tmp/skill_workdir/*, /tmp/skill_workdir/.cache. Show the exact paths first, explain whether they are skill-private temporary paths or user state, and run the cleanup only after the user confirms.

Manage OmniFocus

Use this skill to connect OpenClaw to OmniFocus and work with your tasks, projects, folders, tags, and perspectives in natural language.

Technical note:

• this skill uses the upstream OmniFocus MCP server behind the scenes, but the main goal is helping users review, organize, and update their OmniFocus system faster

Typical things this skill can help with:

• review what is due today or this week
• find flagged tasks, inbox items, or next actions
• create tasks and projects from notes, transcripts, or plans
• reorganize tags, folders, projects, and task metadata
• inspect available perspectives and read what they contain

Quick examples:

• Use $omnifocus-mcp to show me tasks due today.
• Use $omnifocus-mcp to list my flagged tasks for this week.
• Use $omnifocus-mcp to show my Inbox items and suggest how to organize them.
• Use $omnifocus-mcp to create a project called Product Launch with tasks for copy, design, and QA.
• Use $omnifocus-mcp to show the next actions in my Work folder.

Attribution

This skill is an OpenClaw-focused wrapper around the upstream OmniFocus MCP server created by themotionmachine.

Upstream project:

• OmniFocus-MCP
• GitHub: https://github.com/themotionmachine/OmniFocus-MCP
• npm: https://www.npmjs.com/package/omnifocus-mcp

This skill package does not reimplement the MCP server. It documents installation, registration, and OpenClaw-specific usage around the original package.

Refactor credit:

• original MCP server and tool implementation: themotionmachine
• OpenClaw skill adaptation and packaging assistance: OpenAI
• final packaged release, testing, and publishing: the skill publisher

This skill assumes:

• OpenClaw is being used on macOS.
• OmniFocus Pro for Mac is installed locally.
• OmniFocus 3 or later is the safest minimum assumption for this skill.
• The omnifocus-mcp package is installed globally with npm install -g omnifocus-mcp.
• The OpenClaw MCP registry includes an omnifocus server using the omnifocus-mcp executable.

Important compatibility note:

• OmniGroup documents AppleScript support as a Pro feature.
• The upstream MCP server depends on AppleScript.
• The upstream roadmap mentions future support for the planned date added in OmniFocus 4.7, which implies OmniFocus 4.7 is not required for the current feature set.

If the package is missing, OpenClaw can install it from the skill metadata using the configured node manager.

Use {baseDir} when referencing bundled files.

Quick Start

If the MCP server is not configured yet, register it first:

{baseDir}/scripts/register_mcp.sh

To verify the local environment before using the skill:

{baseDir}/scripts/check_setup.sh

The intended OpenClaw MCP definition is:

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

If you want to inspect the registered server after setup:

openclaw mcp show omnifocus --json

Core Workflow

1. Confirm the request is really about OmniFocus, not generic planning advice.
2. Prefer targeted reads before broad dumps.
3. Use the smallest tool that answers the question.
4. Reflect back ambiguous destructive operations before applying them.
5. After write operations, summarize what changed in plain language.

Tool Selection

Prefer these tools in this order:

• query_omnifocus for targeted reads, counts, filtered searches, and lightweight summaries.
• list_tags when you need to discover valid tags before suggesting or applying them.
• list_perspectives and get_perspective_view for perspective-driven workflows.
• dump_database only when the user explicitly needs a broad inventory, deep analysis across the whole database, or the targeted query surface cannot answer the request.
• add_omnifocus_task, add_project, edit_item, remove_item for single-item mutations.
• batch_add_items and batch_remove_items for transcript ingestion, bulk cleanup, or hierarchical task creation.

If the MCP tools are unavailable in the current session, check setup first instead of improvising a replacement workflow.

Query Strategy

Default to query_omnifocus.

Use it for:

• tasks due today, overdue, due this week, or deferred until a date
• next actions, available tasks, blocked tasks, or flagged work
• counts by project or folder
• tasks in a named project or inbox
• project or folder discovery without loading everything

When using query_omnifocus:

• request only the fields you need
• set limit for potentially large result sets
• use summary: true for counts or quick status checks
• sort by dueDate or modificationDate when ordering matters

See {baseDir}/references/query_omnifocus.md for concrete filter guidance.

Mutation Rules

When creating or editing items:

• preserve the user's stated project, folder, tag, defer date, due date, and flag intent
• prefer exact IDs when available; otherwise fall back to names
• use ISO dates for dueDate, deferDate, and plannedDate
• preserve notes instead of overwriting them casually unless the user asked for replacement
• use batch_add_items when the request naturally contains multiple sibling tasks or parent/child structure

For destructive actions:

• remove_item and batch_remove_items should be used only when the user clearly asked to delete or remove the items
• if the target is ambiguous by name, resolve the ambiguity before removing anything

Common Patterns

Daily review

• Fetch urgent work with query_omnifocus on tasks
• filter for status, flagged, dueWithin, or dueOn
• return a concise agenda, then offer follow-up edits only if requested

Inbox processing

• use query_omnifocus with inbox-focused filters first
• group similar tasks
• if the user wants changes, apply them with edit_item or batch_add_items

Project build-out from notes or transcripts

• extract deliverables and action items
• create a project with add_project if needed
• create structured tasks with batch_add_items
• use tempId and parentTempId for hierarchy when subtasks are obvious

Tag cleanup

• call list_tags first if tag names may be uncertain
• identify missing or inconsistent tags with query_omnifocus
• propose the cleanup before mass edits

Perspective Workflows

Use:

• list_perspectives to enumerate built-in and custom perspectives
• get_perspective_view to inspect a named perspective

Important limitation:

• the server can read a named perspective view, but due to OmniJS limitations it cannot programmatically switch perspectives in the GUI

When To Use dump_database

Use dump_database only when one of these is true:

• the user asks for a full OmniFocus inventory
• the user wants cross-cutting analysis that is awkward with targeted queries
• you need a broad export-style snapshot

Avoid it for simple reads because it is slower and heavier than query_omnifocus.

Response Style

When reporting results:

• lead with the answer, not the raw tool call
• keep large task lists grouped and easy to scan
• mention important assumptions, especially around date interpretation
• for write operations, state exactly what was added, edited, or removed

References

• Query filter details: {baseDir}/references/query_omnifocus.md
• OpenClaw MCP registration helper: {baseDir}/scripts/register_mcp.sh
• Local setup check: {baseDir}/scripts/check_setup.sh