omnifocus-mcp

An MCP server for OmniFocus that exposes the full Omni Automation JavaScript API to LLM callers.

macOS only. Requires OmniFocus running on the same machine. The entire implementation runs OmniJS snippets inside OmniFocus via osascript -l JavaScript — no AppleScript string generation, no scripting dictionary limitations.

Prerequisites

• macOS (Omni Automation is macOS-only; the server will not start on other platforms)
• OmniFocus installed and running
• Node.js ≥ 20

Install

The package is published to npm as @scardis/omnifocus-mcp.

Via npx (no install required)

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

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

From source

git clone https://github.com/steveardis/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

Then configure your MCP client:

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

Available Tools

Read

Tool	Description
list_projects	Projects with optional filtering by status, folderId, flagged. Default excludes done/dropped. Limit (default 100).
get_project	Full project detail by stable ID
list_tasks	Tasks scoped by projectId, folderId, inbox: true, or all: true with optional status/tag/due/flagged filters. Limit (default 200).
get_task	Full task detail by stable ID — includes defer/planned/due dates, tags, repetition rule, parentTaskId
list_folders	Folders with optional status filter. Limit (default 200).
get_folder	Full folder detail by stable ID, including child folder and project IDs
list_tags	Tags with optional status filter. Limit (default 200).
get_tag	Full tag detail by stable ID, including child tag IDs
resolve_name	Resolve a name to stable ID candidates — never silently disambiguates; returns all matches

Write

Tool	Description
create_task	Create a task in inbox, project, or as subtask. Supports defer/planned/due dates, tags, flagged, estimated minutes, and repetition rules.
edit_task	Edit any task field. Pass null to clear dates or repetition. Omitted fields are unchanged.
complete_task	Mark a task complete
drop_task	Mark a task dropped
delete_task	Permanently delete a task and all subtasks
create_project	Create a project, optionally in a folder. Supports type, status, review interval, tags.
edit_project	Edit project fields
complete_project	Mark a project complete
drop_project	Mark a project dropped
delete_project	Permanently delete a project and all its tasks
create_folder	Create a folder, optionally nested
edit_folder	Rename a folder
delete_folder	Permanently delete a folder and entire subtree
create_tag	Create a tag, optionally nested
edit_tag	Edit tag name or status
delete_tag	Permanently delete a tag and child tags
move_task	Move a task to a project or make it a subtask of another task
move_project	Move a project to a folder or to top level

Addressing model

Every entity returned by this server includes a stable id field (id.primaryKey from OmniFocus). Use this ID in subsequent calls rather than names. Names can be ambiguous; IDs are not.

If you have a name but not an ID, use resolve_name. It returns a list — if multiple candidates are returned, inspect the path field and ask the user to disambiguate before proceeding with any write operation.

Comparison with other OmniFocus MCP servers

Two notable alternatives exist: themotionmachine/OmniFocus-MCP and [jqlts1/omni

... View full README on GitHub