intervals-mcp

Ein eigenständiger MCP-Server, CLI und Claude-Code-Plugin für lokales Intervals-Zeiterfassung. Beim Starten eines Timers oder Protokollieren eines Zeiteintrags wird zuerst eine lokale SQLite-Datenbank beschrieben; Einträge werden im Hintergrund oder auf Abruf mit Intervals synchronisiert. Berichte und Abfragen sind immer rein lokal und rufen nie die Intervals-API auf.

Installation (Claude-Code-Plugin)

/plugin marketplace add sixfeetup/intervals-mcp
/plugin install intervals@intervals-mcp

Es gibt keinen Build-Schritt: Das dist/-Bundle ist im Repository eingecheckt. Einzige Anforderung ist Node >= 22.5.

Related MCP server: Productivity Tracker MCP Server

Installation (beliebiger MCP-Host)

Klonen Sie das Repository und richten Sie Ihren MCP-Host auf den gebündelten Server aus:

git clone https://github.com/sixfeetup/intervals-mcp.git

{
  "command": "node",
  "args": ["/path/to/intervals-mcp/dist/server.mjs"]
}

Konfiguration

Anmeldedaten und Einstellungen werden in dieser Reihenfolge aufgelöst:

1. Umgebungsvariablen

2. config.json in INTERVALS_HOME (oder ~/.intervals/)

Umgebungsvariablen

config.json-Schlüssel

Wenn Sie eine dateibasierte Konfiguration bevorzugen, erstellen Sie config.json in INTERVALS_HOME (oder ~/.intervals/):

Wenn Sie intervals setup (oder den Schrägstrich-Befehl /intervals-setup) ausführen, wird diese Datei mit Berechtigungen 0600 geschrieben und der API-Schlüssel erscheint nie im Modellkontext – der Schlüssel wird in einer interaktiven, verborgenen Eingabeaufforderung in Ihrem eigenen Terminal eingegeben.

CLI

Das Bundle enthält eine abhängigkeitsfreie CLI (dist/cli.mjs, über package.json#bin als intervals verfügbar, wenn als Paket installiert):

Führen Sie node dist/cli.mjs help aus, um die vollständige Nutzungshilfe anzuzeigen.

Agent-Tools

Wenn sie als Claude-Code-Plugin installiert ist, erscheinen die MCP-Tools unter dem Präfix mcp__plugin_intervals_intervals__:

Alle Toolnamen sind mit mcp__plugin_intervals_intervals__ versehen, wenn sie über das /intervals-Plugin verfügbar gemacht werden.

Funktionsweise

• Timer sind rein lokal. Das Starten eines Timers schreibt eine lokale Zeile nur mit einer Beschreibung. Projekt-, Worktype- und Modul-Hinweise sind optional.

• Laufende Timer können neu klassifiziert werden. Ändern Sie die Projekt-, Worktype- oder Modul-Hinweise eines Timers, bevor Sie ihn stoppen; die Klassifizierung wird beim Anlegen des Zeiteintrags angewendet.

• Stoppen/Anwenden erstellt einen Zeiteintrag. Beim Stoppen eines Timers geben Sie das Projekt an (oder nutzen Standardwerte), und Sie können worktype_id/module_id optional setzen. Wenn keines angegeben ist, werden Standardwerte aus den Projekteinstellungen verwendet – und nur erzwungen, wenn keine Standardwerte vorhanden sind.

• Unerledigte Timer werden erhalten. Wenn Sie einen Timer stoppen, ohne Aufgabe/Worktype/Modul anzugeben, wird der Timer nicht gelöscht. Er wird als „unvollständig" markiert und beim nächsten Start eines neuen Timers automatisch mit Standard-Hinweisen befüllt, wobei start_time und duration_seconds auf 0 gesetzt werden.

• Zeiteinträge sind lokal-first. Beim Stoppen wird ein Zeiteintrag erstellt und sofort versucht, ihn mit Intervals zu synchronisieren. Wenn das fehlschlägt, bleibt er in der Warteschlange und wird bei der nächsten Server-Synchronisierung erneut versucht.

• Das Löschen eines Timers ist sicher. Aktive Timer oder gestoppte Timer ohne erstellten Zeiteintrag können bedenkenlos gelöscht werden. Wenn ein Timer einen zugehörigen lokalen Zeiteintrag hat, schlägt das Löschen fehl und verweist auf die Zeiteintrags-ID. Der Zeiteintrag selbst kann über delete_time_entry gelöscht werden, was den abgeschlossenen Timer ebenfalls entfernt.

• Eine Aktualisierung ist nie automatisch. Der Projektkatalog wird bei der Einrichtung abgerufen und kann jederzeit mit einer Aktualisierung synchronisiert werden – nicht bei jedem Toolaufruf.

• Zeiteinträge werden serverseitig gespeichert. Das Stoppen eines Timers erstellt einen lokalen Zeiteintrag und versucht, ihn sofort zu synchronisieren. Fehlgeschlagene Einträge werden bei späteren Aufrufen erneut versucht.

• Sicherheit. API-Schlüssel werden über eine Umgebungsvariable oder die Konfigurationsdatei bereitgestellt, nie über Toolargumente. Der lokale Speicherort ist ~/.intervals/.