omnifocus-sync-mcp

A headless MCP server that reads and writes OmniFocus data by talking directly to the Omni Sync Server over WebDAV — no Mac, no running OmniFocus app. It implements OmniFocus's client-side end-to-end encryption in TypeScript, so it can run anywhere Node runs (a Linux NAS, a container, a cloud box).

Every other OmniFocus MCP server automates the local macOS app via AppleScript/JXA. This one speaks the cloud sync protocol instead, which is what lets it run headless.

⚠️ Alpha / use at your own risk. This talks to your real task database. The read and write paths have been validated end-to-end against a live Omni Sync Server account (add + delete transactions round-trip correctly), and the crypto and parsing have an offline test suite — but this hasn't been exercised across every OmniFocus version or edge case. Keep a backup (in OmniFocus: File → Back Up Database), and consider a throwaway account while evaluating. See Safety.

How it works

An OmniFocus sync store is a WebDAV collection (OmniFocus.ofocus/) containing:

• a baseline transaction and a chain of delta transactions, each a .zip holding a contents.xml describing object creates/updates/deletes;

• .client files registering each device and the transaction "tail" it has synced to;

• an encrypted plist holding the wrapped document keys.

This server:

1. Resolves the shard — sync.omnigroup.com 302-redirects each account to a syncN.omnigroup.com host; the client follows it.

2. Authenticates with HTTP Digest (what Omni Sync Server negotiates).

3. Decrypts using the OmniFileStore format: PBKDF2 derives a wrapping key from your passphrase, RFC 3394 unwraps the document key slots, and each file is AES-128-CTR + HMAC-SHA256 in 64 KiB segments (encrypt-then-MAC).

4. Replays the transaction chain into an in-memory object model.

5. Writes by building a new contents.xml, zipping, encrypting, PUT-ting it as a new transaction descending from the current head tail, and refreshing its .client registration so other clients treat it as a real participant.

The crypto and format were reimplemented from Omni's own open-source frameworks (OmniGroup/OmniGroup, notably OmniFileStore/EncryptionFormat.md and DecryptionExample.py) plus community reverse-engineering (tomzx/ofocus-format, rubyfocus). See CREDITS.

Related MCP server: OmniFocus MCP Server

Install

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

Configure

Set credentials via environment variables (see .env.example):

Try it without an MCP client

A diagnostic CLI exercises the sync path directly:

export OMNIFOCUS_SYNC_USERNAME=... OMNIFOCUS_SYNC_PASSWORD=...
npm run probe -- sync            # show database counts
npm run probe -- list flagged    # list flagged tasks
npm run probe -- projects        # list projects
npm run probe -- add "Buy milk"  # add an inbox task

Use as an MCP server

Run over stdio. Example Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/absolute/path/to/omnifocus-sync-mcp/dist/index.js"],
      "env": {
        "OMNIFOCUS_SYNC_USERNAME": "your-account",
        "OMNIFOCUS_SYNC_PASSWORD": "your-password"
      }
    }
  }
}

Tools

Safety

• Back up first, and prefer a test account until you trust the write path.

• Start with OMNIFOCUS_READ_ONLY=1 to explore safely.

• Writes are append-only transactions; a bad write forks history rather than destroying data, and OmniFocus merges forks on its next sync — but that is a safety net, not a guarantee.

• Secrets come from the environment only; nothing is written to this repo. The client identity file (client.json) contains no secrets.

Development

npm test          # offline test suite (crypto round-trips, parse/write, digest)
npm run dev -- ... # run the CLI via tsx without building

The offline tests cover the risky parts without a network or a real account: the OmniFileStore encrypt/decrypt round-trip at every segment boundary, MAC tamper detection, the passphrase→PBKDF2→key-unwrap pipeline, contents.xml build/parse round-trips, partial-update merge semantics, and the full zip→encrypt→decrypt→parse read path.

Credits

Built by reimplementing formats documented and open-sourced by others:

• OmniGroup/OmniGroup — Omni's own frameworks; OmniFileStore/EncryptionFormat.md and DecryptionExample.py are the authoritative encryption spec, and OmniFoundation/XML/OFXMLIdentifier.m the id format.

• tomzx/ofocus-format — the .ofocus transaction/format write-up.

• jyruzicka/rubyfocus, kumpelblase2/focus — prior-art parsers.

Not affiliated with or endorsed by The Omni Group. "OmniFocus" is their trademark.

License

MIT — see LICENSE.