FocusBox MCP — Tool-Referenz

Connector-URL: https://focusbox.io/mcp/api. Siehe /mcp für die Einrichtung.

list_today

Gibt die für heute geplanten Aufgaben des Nutzers zurück (nur unerledigte).

Argumente

Keine.

Rückgabewerte

Array von { taskId, name, durationSeconds, projectId }.

Beispielantwort

[
  { "taskId": "abc", "name": "Write spec", "durationSeconds": 1500, "projectId": "mytasks" }
]

next_task

Gibt genau eine Aufgabe zurück, mit der als Nächstes begonnen werden sollte, ausgewählt danach, was in die Zeit bis zum nächsten Kalendertermin passt, was von früheren Tagen liegen geblieben ist und was klein genug für einen Anfang ist. Enthält die Begründung, zwei Alternativen und einen Link zum Starten.

Argumente

availableMinutes (1-480, optional).

Rückgabewerte

{ task, alternatives, freeWindowMinutes, busyNow, message }.

Beispielantwort

{
  "task": {
    "taskId": "abc", "name": "Finish pricing page", "projectId": "work",
    "estimateMinutes": 35, "source": "rollover",
    "reason": "Carried over from 2 days ago; fits the 47 min you have before your next meeting.",
    "startUrl": "https://focusbox.io/now?id=work&taskId=abc"
  },
  "alternatives": [],
  "freeWindowMinutes": 47, "busyNow": false,
  "message": "Start here: Finish pricing page (35 min)."
}

get_streams

Listet die FocusBox-Projekte des Nutzers auf (Container für Aufgaben; in der API aus historischen Gründen "streams" genannt). Archivierte Projekte sowie die today/mytasks-Buckets sind ausgeschlossen.

Argumente

Keine.

Rückgabewerte

Array von { streamId, name }.

add_task

Fügt einem Projekt eine neue Aufgabe hinzu oder plant sie für heute ein. Die Standarddauer beträgt 25 Minuten.

Argumente

Rückgabewerte

{ taskId, streamId, name, durationSeconds }.

update_task

Aktualisiert ein oder mehrere Felder einer bestehenden Aufgabe: name, durationSeconds oder dueDate.

Argumente

Rückgabewerte

{ taskId, streamId, name, durationSeconds, dueDate }.

delete_task

Löscht eine Aufgabe dauerhaft. Idempotent: Das Löschen einer bereits gelöschten Aufgabe ist kein Fehler.

Argumente

Rückgabewerte

{ taskId, streamId, deleted, reason? }.

complete_task

Markiert eine FocusBox-Aufgabe als erledigt.

Argumente

Rückgabewerte

{ taskId, streamId, completed: true }.

get_insights_30d

Aggregierte Übersicht über die in den letzten 30 Tagen erledigten Aufgaben des Nutzers.

Argumente

Keine.

Rückgabewerte

{ totalTasks, totalFocusMinutes, topStreams[{streamId, name, tasks}, days: 30 }].

Authentifizierung

OAuth (empfohlen für Claude)

Claude Desktop und claude.ai im Web schließen den OAuth-Flow automatisch ab. Es ist keine manuelle Verwaltung von API-Schlüsseln nötig.

Bearer (Cursor, Inspector, eigene Clients)

Hole dir deinen API-Schlüssel unter /account/api-keys (beginnt mit apikey_). Sende ihn bei jeder Anfrage als Authorization: Bearer apikey_xxx.

Rate-Limits

300 Tool-Aufrufe pro 2 Minuten je API-Schlüssel. 60 nicht authentifizierte Probes pro 2 Minuten je IP.

FAQ