omnifocus-mcp

Ein MCP-Server für OmniFocus, der LLM-Aufrufern die vollständige Omni-Automation-JavaScript-API zugänglich macht.

Nur macOS. Erfordert, dass OmniFocus auf demselben Rechner läuft. Die gesamte Implementierung führt OmniJS-Snippets über osascript -l JavaScript innerhalb von OmniFocus aus — keine AppleScript-Stringgenerierung, keine Einschränkungen durch das Skriptwörterbuch.

Voraussetzungen

• macOS (Omni Automation ist nur für macOS verfügbar; der Server startet auf anderen Plattformen nicht)

• OmniFocus installiert und läuft

• Node.js ≥ 20

Related MCP server: OmniFocus MCP Server

Installation

Das Paket ist als @scardis/omnifocus-mcp auf npm veröffentlicht.

Über npx (keine Installation erforderlich)

Füge es zu deiner MCP-Client-Konfiguration hinzu (z. B. Claude Desktop claude_desktop_config.json):

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

Aus dem Quellcode

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

Konfiguriere anschließend deinen MCP-Client:

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

Verfügbare Tools

Lesen

Schreiben

Adressierungsmodell

Jede von diesem Server zurückgegebene Entität enthält ein stabiles id-Feld (id.primaryKey aus OmniFocus). Verwende diese ID in nachfolgenden Aufrufen anstelle von Namen. Namen können mehrdeutig sein; IDs nicht.

Wenn du einen Namen, aber keine ID hast, verwende resolve_name. Es gibt eine Liste zurück — wenn mehrere Kandidaten zurückgegeben werden, prüfe das path-Feld und bitte den Benutzer, die Mehrdeutigkeit aufzulösen, bevor du eine Schreiboperation durchführst.

Vergleich mit anderen OmniFocus-MCP-Servern

Es gibt zwei erwähnenswerte Alternativen: themotionmachine/OmniFocus-MCP und jqlts1/omnifocus-mcp-enhanced (ein Fork des obigen mit zusätzlichen Werkzeugen).

Skript-API. Die Alternativen verwenden das JXA-Skriptwörterbuch oder AppleScript, um OmniFocus zu steuern. Dieser Server führt einen einzigen JXA-Aufruf aus — Application('OmniFocus').evaluateJavascript() — und lässt die gesamte Logik als OmniJS (Omni Automation) innerhalb von OmniFocus laufen. Dies ermöglicht Zugriff auf den vollständigen Omni-Automation-API-Umfang (Wiederholungsregeln, Review-Intervalle, Perspektiven, Forecast, Anhänge, URL-Automation usw.) statt des eingeschränkteren Skriptwörterbuchs.

Argument-Injektion. Die Alternativen konstruieren osascript-Befehle per String-Interpolation, was bei Apostrophen, Anführungszeichen, Backslashes und Unicode in Namen zu Fehlern führen kann. Dieser Server serialisiert alle Argumente mit JSON.stringify in ein JS-Literal.

Entitätsadressierung. Die Alternativen adressieren Entitäten hauptsächlich über den Namen. Dieser Server gibt für jede Entität eine stabile id (id.primaryKey) zurück und stellt resolve_name bereit, um einen Namen auf ID-Kandidaten abzubilden — er liefert alle Treffer mit vollständigen Pfaden, statt bei mehrdeutigen Namen stillschweigend einen auszuwählen.

Vollständiges CRUD. Dieser Server unterstützt das Erstellen, Bearbeiten, Abschließen, Verwerfen, Löschen und Verschieben von Aufgaben, Projekten, Ordnern und Tags — sowie Wiederholungsregeln und das geplante Datum von OmniFocus 4.

Entwicklung

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

Testen

Unit-Tests (kein OmniFocus erforderlich)

npm test

Integrationstests

⚠️ Integrationstests laufen gegen deine echte OmniFocus-Datenbank.

Jeder Testlauf erstellt einen temporären Ordner auf oberster Ebene mit dem Namen __MCP_TEST_<uuid>__ und löscht ihn beim Teardown. Wenn ein Testlauf vor dem Teardown unterbrochen wird, führe das Cleanup-Skript aus:

npm run test:cleanup-fixtures

⚠️ Sync-Warnung: Standardmäßig weigern sich die Integrationstests zu laufen, wenn die OmniFocus-Synchronisierung aktiviert ist, um zu verhindern, dass Test-Fixtures auf deine anderen Geräte übertragen werden. Deaktiviere zuerst die OmniFocus-Synchronisierung oder setze MCP_TEST_ALLOW_SYNC=1, um dich zu entscheiden (die Fixtures werden dann synchronisiert):

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

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

Veraltete Test-Fixtures aufräumen

npm run test:cleanup-fixtures

Dies entfernt alle __MCP_TEST_*__-Ordner und verwaiste __mcp_*__-Projekte/Tags, die von unterbrochenen Testläufen in OmniFocus zurückgeblieben sind.

Mitwirken

Beiträge sind willkommen! So legst du los:

1. Forke und klone das Repository

2. Installiere Abhängigkeiten: npm install

3. Führe Unit-Tests aus (kein OmniFocus erforderlich): npm test

4. Führe Integrationstests aus (erfordert macOS + OmniFocus): npm run test:integration

Vor dem Einreichen eines PR

• npm run typecheck — muss ohne Fehler durchlaufen

• npm test — alle Unit-Tests müssen bestehen

• npm run test:integration — alle Integrationstests müssen bestehen (nur macOS)

• Änderungen fokussiert halten — ein Feature oder Fix pro PR

Architekturübersicht

Der Server führt OmniJS-Snippets über osascript -l JavaScript innerhalb von OmniFocus aus. Jedes Tool hat drei Ebenen:

• Schema (src/schemas/shapes.ts) — Zod-Schemas zur Eingabevalidierung und zum Parsen der Ausgabe

• Snippet (src/snippets/*.js) — OmniJS-Code, der innerhalb von OmniFocus läuft. Reines ES5-JavaScript (keine Imports, kein TypeScript). Argumente werden über den __ARGS__-Platzhalter injiziert.

• Tool-Handler (src/tools/*.ts) — Validiert Eingaben, ruft runSnippet() auf und parst das Ergebnis

Wenn du ein neues Tool hinzufügst:

1. Definiere Eingabe-/Ausgabeschemas in src/schemas/shapes.ts und exportiere sie aus src/schemas/index.ts

2. Erstelle das OmniJS-Snippet in src/snippets/

3. Füge den Snippet-Namen zu ALLOWED_SNIPPETS in src/runtime/snippetLoader.ts hinzu

4. Erstelle den Tool-Handler in src/tools/ und registriere ihn in src/tools/index.ts

5. Füge Unit-Tests für Schemas und Integrationstests hinzu, die gegen OmniFocus laufen

OmniJS-Snippets schreiben

Snippets laufen in der JavaScript-Laufzeitumgebung von OmniFocus, nicht in Node.js. Wichtige Einschränkungen:

• JavaScript im ES5-Stil — verwende var, function(){}, keine Pfeilfunktionen in älteren OmniFocus-Versionen

• Keine Imports — alle OmniJS-Globals (flattenedTasks, flattenedProjects, moveTasks usw.) sind direkt verfügbar

• JSON zurückgeben — gib immer return JSON.stringify({ ok: true, data: ... }) zurück

• Fehlermuster — wirf benannte Fehler (NotFoundError, ValidationError), die die Brücke abfängt und umschließt

Lizenz

MIT