How do I install Omnifocus?

Omnifocus is a local plugin. Install it using npm package: @scardis/omnifocus-mcp and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

What AI apps work with Omnifocus?

Omnifocus uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Omnifocus MCP Server

by User

ProductivityModerate6.0LocalNew

Free

Full CRUD MCP server for OmniFocus via Omni Automation — tasks, projects, folders, tags, recurrence.

About

Full CRUD MCP server for OmniFocus via Omni Automation — tasks, projects, folders, tags, recurrence.

Security Report

6.0

Moderate6.0Moderate Risk

Valid MCP server (1 strong, 1 medium validity signals). 3 known CVEs in dependencies (1 critical, 2 high severity) Imported from the Official MCP Registry. 1 finding(s) downgraded by scanner intelligence.

8 files analyzed · 4 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

Shell Command Execution

Runs commands on your machine. Be cautious — only use if you trust this plugin.

How to Install

Add this to your MCP configuration file:

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

Documentation

View on GitHub

From the project's GitHub README.

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/omnifocus-mcp-enhanced (a fork of the above with additional tools).

Scripting API. The alternatives use the JXA scripting dictionary or AppleScript to drive OmniFocus. This server makes a single JXA call — Application('OmniFocus').evaluateJavascript() — and runs all logic as OmniJS (Omni Automation) inside OmniFocus. This gives access to the full Omni Automation API surface (recurrence rules, review intervals, perspectives, forecast, attachments, URL automation, etc.) rather than the more limited scripting dictionary.

Argument injection. The alternatives construct osascript commands via string interpolation, which can break on apostrophes, quotes, backslashes, and unicode in names. This server serializes all arguments with JSON.stringify into a JS literal.

Entity addressing. The alternatives address entities primarily by name. This server returns a stable id (id.primaryKey) for every entity and provides resolve_name to map a name to ID candidates — returning all matches with full paths rather than silently picking one when names are ambiguous.

Full CRUD. This server supports creating, editing, completing, dropping, deleting, and moving tasks, projects, folders, and tags — plus repetition rules and OmniFocus 4's planned date.

Development

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

Testing

Unit tests (no OmniFocus required)

npm test

Integration tests

⚠️ Integration tests run against your real OmniFocus database.

Each test run creates a temporary top-level folder named __MCP_TEST_<uuid>__ and deletes it on teardown. If a test run is interrupted before teardown, run the cleanup script:
npm run test:cleanup-fixtures

⚠️ Sync warning: By default, integration tests refuse to run if OmniFocus sync is enabled, to prevent test fixtures from propagating to your other devices. Disable OmniFocus sync first, or set MCP_TEST_ALLOW_SYNC=1 to opt in (fixtures will sync):

# Default (refuses if sync enabled)
npm run test:integration

# With sync enabled (use carefully)
MCP_TEST_ALLOW_SYNC=1 npm run test:integration

Clean up stale test fixtures

npm run test:cleanup-fixtures

This removes any __MCP_TEST_*__ folders and orphaned __mcp_*__ projects/tags left in OmniFocus from interrupted test runs.

Contributing

Contributions are welcome! Here's how to get started:

Fork and clone the repo
Install dependencies: npm install
Run unit tests (no OmniFocus needed): npm test
Run integration tests (requires macOS + OmniFocus): npm run test:integration

Before submitting a PR

npm run typecheck — must pass with no errors
npm test — all unit tests must pass
npm run test:integration — all integration tests must pass (macOS only)
Keep changes focused — one feature or fix per PR

Architecture overview

The server runs OmniJS snippets inside OmniFocus via osascript -l JavaScript. Each tool has three layers:

Schema (src/schemas/shapes.ts) — Zod schemas for input validation and output parsing
Snippet (src/snippets/*.js) — OmniJS code that runs inside OmniFocus. Plain ES5 JavaScript (no imports, no TypeScript). Arguments are injected via __ARGS__ placeholder.
Tool handler (src/tools/*.ts) — Validates input, calls runSnippet(), parses the result

When adding a new tool:

Define input/output schemas in src/schemas/shapes.ts and export from src/schemas/index.ts
Create the OmniJS snippet in src/snippets/
Add the snippet name to ALLOWED_SNIPPETS in src/runtime/snippetLoader.ts
Create the tool handler in src/tools/ and register it in src/tools/index.ts
Add unit tests for schemas and integration tests that run against OmniFocus

Writing OmniJS snippets

Snippets run inside OmniFocus's JavaScript runtime, not Node.js. Key constraints:

ES5-style JavaScript — use var, function(){}, no arrow functions in older OmniFocus versions
No imports — all OmniJS globals (flattenedTasks, flattenedProjects, moveTasks, etc.) are available directly
Return JSON — always return JSON.stringify({ ok: true, data: ... })
Error pattern — throw named errors (NotFoundError, ValidationError) which the bridge catches and wraps