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

Write

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 (compiles TypeScript and copies snippets into dist/)
npm run build

Publishing a new version is documented in RELEASING.md.

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:

Terminal

Copy

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:

1. Fork and clone the repo
2. Install dependencies: npm install
3. Run unit tests (no OmniFocus needed): npm test
4. 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:

1. Define input/output schemas in src/schemas/shapes.ts and export from src/schemas/index.ts
2. Create the OmniJS snippet in src/snippets/
3. Add the snippet name to ALLOWED_SNIPPETS in src/runtime/snippetLoader.ts
4. Create the tool handler in src/tools/ and register it in src/tools/index.ts
5. 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

License

MIT