OmniFocus MCP Server

Ein Model Context Protocol (MCP)-Server, der OmniFocus mit Claude und anderen MCP-kompatiblen KI-Assistenten verbindet.

Überblick

Dieser Server verbindet KI-Assistenten mit Ihrer OmniFocus-Datenbank. Durch natürliche Konversation kann ein Assistent Aufgaben und Projekte abfragen, erstellen, bearbeiten und entfernen – einschließlich Stapeloperationen. Einige Dinge, die Sie damit tun können:

• Ein Syllabus-PDF in ein vollständig spezifiziertes Projekt mit Aufgaben, Tags, Aufschiebedaten und Fälligkeitsdaten übersetzen

• Ein Meeting-Transkript in eine Liste von Aktionen verwandeln

• Ihre Tags, Projekte und Ordner im Gespräch prüfen und neu organisieren

• Visualisierungen Ihrer Aufgaben, Projekte und Tags erstellen

• Dutzende von Elementen in einem einzigen Stapelvorgang verarbeiten

Related MCP server: MCP OmniFocus

Schnellstart

Voraussetzungen

• macOS mit installiertem OmniFocus

• Node.js 20 oder höher (für npx)

Beim ersten Gespräch mit OmniFocus fragt macOS, ob Sie den Automatisierungszugriff erlauben möchten. Erlauben Sie es einmal, und Sie sind bereit.

Claude Desktop

Fügen Sie den Server zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Starten Sie dann Claude Desktop neu.

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp

Andere MCP-Clients funktionieren auf die gleiche Weise: Starten Sie npx -y omnifocus-mcp über stdio.

Beispielkonversationen

Gezielte Abfragen:

„Zeig mir alle meine markierten Aufgaben, die diese Woche fällig sind"

„Was sind meine nächsten Aktionen im Ordner Arbeit?"

„Zähle, wie viele Aufgaben in jedem Projekt sind"

Neu organisieren:

„Ich möchte, dass jede Aufgabe ein Energieniveau-Tag hat. Zeig mir eine Liste aller Aufgaben, die keins haben, und deine Vorschläge, welches Tag hinzugefügt werden soll. Ich nehme alle Änderungen vor, die ich für angemessen halte. Dann nimm die Änderungen in OmniFocus vor."

Von überall erfassen:

„Ok, danke für die ausführliche Erklärung, warum die Rechtsstaatlichkeit wichtig ist. Füge meinem Aktivismus-Projekt eine wiederkehrende Aufgabe hinzu, die mich wöchentlich daran erinnert, meinen Abgeordneten anzurufen. Füge eine Zusammenfassung dieses Gesprächs in das Notizfeld ein."

Mit Perspektiven arbeiten:

„Welche Perspektiven habe ich zur Verfügung?"

„Zeig mir, was in meiner Inbox-Perspektive ist"

Transkripte oder PDFs verarbeiten:

„Ich füge das Transkript des heutigen Meetings ein. Bitte analysiere es und erstelle Aufgaben in OmniFocus für alle Aktionspunkte, die mir zugewiesen sind. Lege sie in mein Projekt ‚Produktentwicklung'."

Werkzeuge

Der Server bietet 12 Werkzeuge. Optionale Parameter sind markiert.

query_omnifocus

Fragen Sie Aufgaben, Projekte oder Ordner mit gezielten Filtern ab – viel schneller und leichter als die gesamte Datenbank zu laden. Siehe QUERY_TOOL_REFERENCE.md für die vollständige Referenz und QUERY_TOOL_EXAMPLES.md für ausgearbeitete Beispiele.

Verfügbare Filter:

• Container: projectName (Groß-/Kleinschreibung nicht beachtende Teilübereinstimmung; "inbox" zielt auf den Posteingang), projectId, folderId (enthält Unterordner), folderName (Groß-/Kleinschreibung nicht beachtende Teilübereinstimmung, enthält Unterordner)

• Namen: taskName (Groß-/Kleinschreibung nicht beachtende Teilübereinstimmung)

• Tags: tags (exakte Übereinstimmung, Groß-/Kleinschreibung beachtend)

• Status: status – Aufgaben: Next, Available, Blocked, DueSoon, Overdue, Completed, Dropped; Projekte: Active, OnHold, Done, Dropped

• Daten, zukunftsgerichtet: dueWithin, deferredUntil, plannedWithin (Bereiche), dueOn, deferOn, plannedOn (exakter Tag). Akzeptiert eine Anzahl von Tagen, "today", "tomorrow", "this week", "next week" oder ein ISO-Datum

• Daten, rückblickend: addedWithin, addedOn, completedWithin, completedOn, droppedWithin, droppedOn (abgeschlossene/verworfene Filter erfordern includeCompleted: true)

• Markierungen & Sonstiges: flagged, inbox, hasNote, isRepeating, reviewDue (nur Projekte)

dump_database

Den vollständigen Zustand Ihrer Datenbank abrufen. Für umfassende Analysen verwenden; für alles Gezielte query_omnifocus bevorzugen.

• hideCompleted (optional): abgeschlossene/verworfene Aufgaben ausblenden (Standard: true)

• hideRecurringDuplicates (optional): doppelte Instanzen wiederkehrender Aufgaben ausblenden (Standard: true)

add_omnifocus_task

Eine neue Aufgabe erstellen.

• name

• projectName (optional): Projekt, dem die Aufgabe hinzugefügt werden soll (Standard: Posteingang)

• parentTaskId / parentTaskName (optional): unter einer vorhandenen Aufgabe verschachteln

• note, dueDate, deferDate, plannedDate, flagged, estimatedMinutes, tags (alle optional)

• repeat (optional): wiederkehrend machen – siehe Wiederkehrende Elemente

add_project

Ein neues Projekt erstellen.

• name

• folderName (optional): Ordner, in dem das Projekt platziert werden soll

• sequential (optional): ob Aufgaben in Reihenfolge abgeschlossen werden müssen

• note, dueDate, deferDate, flagged, estimatedMinutes, tags, repeat (alle optional)

edit_item

Ein vorhandenes Element (Aufgabe oder Projekt) bearbeiten. Auch der Weg, Elemente zu verschieben – setzen Sie newProjectName, um eine Aufgabe in ein Projekt zu verschieben, oder auf ""/"inbox", um sie in den Posteingang zu senden.

• id oder name: welches Element bearbeitet werden soll (id hat Vorrang)

• itemType: task oder project

• Gemeinsam: newName, newNote, newDueDate, newDeferDate, newFlagged, newEstimatedMinutes (Daten im ISO-Format; leere Zeichenfolge löscht)

• Aufgaben: newStatus (incomplete, completed, dropped, skipped – skipped nur für wiederkehrende Aufgaben), addTags, removeTags, replaceTags, newProjectName, newPlannedDate

• Projekte: newProjectStatus (active, completed, dropped, onHold), newFolderName, newSequential, markReviewed (setzt das nächste Überprüfungsdatum basierend auf dem Überprüfungsintervall des Projekts)

• Wiederholung: newRepeat setzt eine neue Regel (gleiche Form wie repeat beim Erstellen); newRepeat: null löscht sie

remove_item

Eine Aufgabe oder ein Projekt entfernen.

• id oder name: welches Element entfernt werden soll

• itemType: task oder project

batch_add_items

Mehrere Aufgaben und Projekte in einem Vorgang erstellen. Jedes Element akzeptiert dieselben Felder wie add_omnifocus_task / add_project, plus type (task oder project) und optionale Hierarchie-Helfer:

• tempId: eine temporäre ID, auf die andere Elemente im selben Stapel verweisen können

• parentTempId: dieses Element unter der tempId eines anderen Stapelelements verschachteln

{
  "items": [
    { "type": "project", "name": "My Project", "tempId": "proj1" },
    { "type": "task", "name": "First task", "parentTempId": "proj1" },
    { "type": "task", "name": "Parent task", "parentTempId": "proj1", "tempId": "t1" },
    { "type": "task", "name": "Subtask", "parentTempId": "t1" }
  ]
}

batch_remove_items

Mehrere Aufgaben oder Projekte in einem Vorgang entfernen. Jedes Element nimmt id oder name sowie itemType.

list_perspectives

Verfügbare Perspektiven auflisten, sowohl integrierte als auch benutzerdefinierte (benutzerdefinierte Perspektiven sind ein OmniFocus-Pro-Feature).

• includeBuiltIn, includeCustom (optional, Standard: true)

get_perspective_view

Die in einer benannten Perspektive sichtbaren Elemente abrufen.

• perspectiveName: z. B. Inbox, Flagged oder ein benutzerdefinierter Perspektivenname

• limit (optional, Standard: 100), includeMetadata (optional), fields (optional)

list_tags

Alle Tags mit ihrer Hierarchie, ihrem aktiven Status und ihren Aufgabenzählungen auflisten.

• includeDropped (optional, Standard: false)

create_tag

Ein Tag erstellen, optional unter einem vorhandenen übergeordneten Tag verschachtelt.

• name

• parentTagName / parentTagID (optional; ID hat Vorrang)

Wiederkehrende Elemente

add_omnifocus_task, add_project und jedes Element in batch_add_items akzeptieren ein repeat-Objekt; edit_item akzeptiert newRepeat. Sie beschreiben den Zeitplan, und der Server kompiliert die ICS-Wiederholungsregel, sodass Sie nie eine RRULE von Hand schreiben müssen.

{ "name": "Weekly review", "repeat": { "method": "start-after-completion", "unit": "week" } }
{ "name": "Strength work", "repeat": { "method": "fixed", "unit": "week", "weekdays": ["TU","TH"] } }

Wählen Sie method bewusst – es ist das Feld, das am häufigsten von Hand falsch gesetzt wird. Bei fixed erscheinen Vorkommen nach Zeitplan, unabhängig davon, ob das letzte erledigt wurde, sodass eine verpasste Woche einen Rückstand hinterlässt. Bei start-after-completion wird das nächste Vorkommen ab dem tatsächlichen Abschluss geplant, sodass die Gewohnheit einfach wieder aufgenommen wird.

Lesen Sie eine Regel mit query_omnifocus über die Felder repetitionRule (ICS-String) und repetitionMethod zurück oder filtern Sie mit isRepeating.

Derzeit nicht unterstützt: positionsbasierte monatliche Regeln („dritter Dienstag"), bestimmte Monatstage und Endbedingungen (COUNT/UNTIL). Setzen Sie diese direkt in OmniFocus.

Ressourcen

Ressourcen ermöglichen es MCP-Clients, OmniFocus-Daten als Kontext an eine Konversation anzuhängen, ohne Werkzeugaufrufe. In Claude Code tippen Sie @, um sie zu durchsuchen; Claude Desktop und andere ressourcenbewusste Clients können sie direkt anhängen. Alle Ressourcen geben JSON zurück.

Die beiden Vorlagenressourcen unterstützen das Auflisten aller verfügbaren Werte und die automatische Vervollständigung des Parameters {name}.

Serveranweisungen & Protokollierung

Anweisungen: Während des MCP-Handshakes sendet der Server Nutzungsanleitungen an den Client – Werkzeugauswahl-Empfehlungen (bevorzugen Sie query_omnifocus gegenüber dump_database), Filtertipps und den Ressourcenkatalog. Keine Konfiguration erforderlich.

Protokollierung: Der Server sendet strukturierte Protokolle über das MCP-Protokollierungsprotokoll. Clients können die Ausführlichkeit mit logging/setLevel anpassen (debug, info, warning, error, ...). Skriptausführungszeiten und Fehler werden automatisch protokolliert.

So funktioniert es

Der Server kommuniziert mit OmniFocus über osascript und verwendet dabei JXA (JavaScript for Automation) und OmniFocus' eingebettete Omni Automation (OmniJS), wo dies angebracht ist. Er basiert auf dem offiziellen MCP TypeScript SDK und spricht mit Clients über stdio.

Gemeinsamer Daemon

Das Starten von omnifocus-mcp startet einen kleinen Shim, der sich mit einem gemeinsamen Hintergrund-Daemon verbindet und einen startet, falls noch keiner läuft. Jeder Client auf dem Rechner erhält seine eigene unabhängige MCP-Sitzung, aber alle laufen in diesem einen Prozess.

Das ist wichtig, wenn mehrere Agenten OmniFocus gleichzeitig verwenden. OmniFocus ist eine single-threaded Anwendung, die über AppleEvents gesteuert wird, und der Server begrenzt, wie viele osascript-Aufrufe er gleichzeitig ausführt. Wenn jeder Client seinen eigenen Server hatte, war diese Begrenzung pro Prozess – zehn Clients bedeuteten zehn unabhängige Budgets, die auf eine App gerichtet waren, was zu AppleEvent-Zeitüberschreitungen führte. Durch die gemeinsame Nutzung eines Prozesses wird die Begrenzung global.

Der Daemon lauscht auf einem Unix-Domain-Socket in einem 0700-Verzeichnis (standardmäßig ~/.omnifocus-mcp/daemon-<version>.sock), sodass der Zugriff durch das Dateisystem erzwungen wird – kein Netzwerkport und kein Token. Er beendet sich von selbst, sobald für das Leerlauffenster kein Client verbunden war, und protokolliert in daemon.log neben dem Socket.

Der Socket-Name trägt die Paketversion, sodass ein Upgrade nie dazu führen kann, dass Sie mit dem Daemon der vorherigen Version sprechen. Direkt nach einem Upgrade können Sie kurzzeitig zwei Daemons sehen: Der alte bedient weiterhin die bereits verbundenen Clients und beendet sich, sobald der letzte von ihnen die Verbindung trennt. Clients, die noch mit dem alten Daemon verbunden sind, werden darüber in-band informiert – während ein neuerer Daemon läuft, enthält jedes Tool-Ergebnis einen einzeiligen Upgrade-Hinweis, sodass niemand daran denken muss, sich neu zu verbinden.

An der Client-Konfiguration ändert sich nichts. Wenn der Daemon nicht gestartet werden kann – eine ungewöhnliche Sandbox, ein schreibgeschütztes Home-Verzeichnis – fällt der Shim auf einen eigenständigen Server im Prozess zurück, genau wie in früheren Versionen.

Umgebungsvariablen

Fahrplan

• MCP-prompt-Unterstützung

• Bearbeiten von Benachrichtigungen für Projekte und Aufgaben

• Siehe die GitHub Issues für Feature-Anfragen und bekannte Probleme

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull-Request einzureichen. CI führt bei jedem PR Typprüfung, Unit-Tests und einen Build aus.

npm install
npm test            # unit tests
npm run build       # compile to dist/
npm run test:integration  # requires OmniFocus; creates and removes TEST:-prefixed items

Lizenz

MIT