Workel MCP Server

Der offizielle Model Context Protocol-Server für Workel – ein schlanker, zustandsloser Client der Workel Public API v1. Er stellt einen Workel-Arbeitsbereich KI-Agenten (Claude, dem OpenAI Agents SDK oder jedem anderen MCP-fähigen Client) als eine kleine Menge klar abgegrenzter Tools zur Verfügung. Jede Regel, die tatsächlich zählt – was dieser Schlüssel sehen kann, was er schreiben kann, wie schnell er schreiben kann – lebt in der Workel-API selbst; dieses Paket besitzt keine Autorität, die der Schlüssel nicht bereits hat. Eine curl-Anfrage mit demselben Schlüssel kann genau das tun, was dieser Server tun kann, nicht mehr.

Für die vollständige Einrichtung pro Client (Claude Desktop, Claude Code, projektspezifische .mcp.json und das OpenAI Agents SDK) siehe die Workel-Entwicklerdokumentation.

Claude verwenden? Dieses Paket brauchen Sie wahrscheinlich nicht

Workel betreibt einen gehosteten MCP-Server. Fügen Sie ihn in Claude unter Einstellungen → Verbindungen → Benutzerdefinierte Verbindung hinzufügen hinzu:

https://mcp.workel.com/mcp

Sie melden sich bei Workel an, wählen einen Arbeitsbereich aus und sind verbunden. Keine Installation, keine Konfigurationsdatei und kein API-Schlüssel – Sie sehen keinen und Claude auch nicht. Die Autorisierung erfordert Besitzer- oder Admin-Rechte auf dem von Ihnen gewählten Arbeitsbereich, und die Verbindung wird bei jeder Anfrage erneut überprüft. Wenn Sie diese Rolle verlieren, wird die Verbindung getrennt, ohne dass jemand daran denken muss, einen Schlüssel zu widerrufen.

Es kann Ihre Projekte, Aufgaben, Kommentare, Ereignisse und Mitglieder lesen – einschließlich des Titelbilds einer Aufgabe, Anhängen und des vollständigen Verlaufs – und es kann Aufgaben, Kommentare und Ereignisse erstellen und vorhandene Aufgaben aktualisieren: sie umbenennen, Daten und Priorität ändern, sie zwischen Spalten und Projekten verschieben und ändern, wem sie zugewiesen sind. Es kann nichts löschen und keine Dateien hochladen. Lese- und Schreibberechtigungen werden auf dem Zustimmungsbildschirm getrennt aufgeführt, sodass Sie sie bewusst genehmigen, anstatt sie später zu entdecken.

Mehr als einen Arbeitsbereich verbinden

Eine Verbindung deckt einen Arbeitsbereich ab, da die dahinterstehende Anmeldeinformation an diesen Arbeitsbereich gebunden ist. Um einen zweiten zu erreichen, fügen Sie die Verbindung erneut hinzu und wählen Sie den anderen Arbeitsbereich – jede Verbindung wird separat registriert, sodass sie nebeneinander bestehen, und jede erscheint unter dem Namen ihres Arbeitsbereichs (workel — Acme) und nicht als identische Einträge, die Sie nicht unterscheiden können.

Ein Punkt, den Sie beachten sollten: Die erneute Autorisierung einer bestehenden Verbindung verschiebt sie, sie fügt nicht hinzu. Wenn Sie die Zustimmung für eine bereits hinzugefügte Verbindung erneut durchlaufen, ersetzt dies deren Anmeldeinformation und deaktiviert die alte, sodass diese Verbindung zu dem Arbeitsbereich wechselt, den Sie wählen. Wenn Sie beide möchten, fügen Sie eine neue Verbindung hinzu, anstatt die vorhandene erneut zu autorisieren.

Related MCP server: Google Workspace MCP Server

Selbst ausführen

Dieses Paket ist für die Fälle gedacht, die der gehostete Server nicht abdeckt: Claude Code, CI-Agenten, das OpenAI Agents SDK – überall dort, wo Sie den Prozess selbst ausführen und die Anmeldeinformation selbst verwalten möchten. Alles unten dreht sich darum.

Es behandelt mehrere Arbeitsbereiche anders und besser für diesen Anwendungsfall: Setzen Sie WORKEL_API_KEYS auf eine durch Kommas getrennte Liste, einen Schlüssel pro Arbeitsbereich, und jedes Tool erhält ein workspace-Argument, das angibt, in welchem es agieren soll. Zehn Tools bleiben zehn Tools, egal wie viele Arbeitsbereiche Sie konfigurieren, anstatt sich pro Arbeitsbereich zu vervielfachen – was wichtig ist, weil jede Tool-Definition Kontext ist, den das Modell bei jeder Runde bezahlt.

Erstellen Sie vor dem Start einen dedizierten Nur-Lese-Schlüssel

Bevor Sie einen KI-Client auf diesen Server richten, gehen Sie zu Workel → Einstellungen → Entwickler und erstellen Sie einen neuen API-Schlüssel nur für diesen Zweck – verwenden Sie keinen Schlüssel wieder, den bereits eine andere Integration besitzt. Das Erstellen eines Schlüssels erfordert eine Besitzer- oder Admin-Rolle. Gewähren Sie ihm nur die read:*-Bereiche, die die Tools dieser Version tatsächlich verwenden (read:projects, read:tasks, read:members, read:events – siehe Tools unten); lassen Sie jeden write:*-Bereich deaktiviert, es sei denn, Sie haben bewusst entschieden, einem Agenten zu erlauben, selbstständig Dinge in Ihrem Arbeitsbereich zu erstellen und zu bearbeiten. Verwenden Sie einen Schlüssel pro Maschine oder Agent, benennen Sie ihn so, dass Sie sich später merken, wofür er ist, und wenn eine Maschine ausgemustert oder ein Client kompromittiert wird, widerrufen Sie diesen einen Schlüssel in Einstellungen → Entwickler, anstatt einen Schlüssel zu rotieren, den mehrere Tools teilen – der Widerruf ist sofort wirksam und greift bei der nächsten Anfrage.

Zwei Dinge, die Sie verstehen sollten, bevor Sie die unten beschriebenen Flags anfassen:

• WORKEL_ENABLE_WRITES ist ein lokales Operator-Zustimmungs-Flag, keine Autorisierungsgrenze. Es kann nur einschränken, was einem bereits eingeschränkten Schlüssel angeboten wird, niemals erweitern – und da es in einer Konfigurationsdatei oder Umgebungsvariable lebt, auf die ein KI-Codierungsagent typischerweise Schreibzugriff hat, kann ein auf Ihrer Maschine laufender Agent es selbst wieder auf true setzen. Ein lokales Flag ist nichts, von dem man erwarten kann, dass ein nicht vertrauenswürdiger Agent es in Ruhe lässt. Die eigenen Bereiche des Schlüssels – bewusst bei der Erstellung gewährt und jederzeit widerrufbar – sind das eigentliche Tor.

• Eine WORKEL_API_BASE_URL-Überschreibung sendet Ihren Schlüssel an einen anderen Host. Jede Anfrage, die dieser Server stellt, enthält Ihren Schlüssel im Authorization-Header. Wenn WORKEL_API_BASE_URL jemals auf eine URL zeigt, die Sie nicht kontrollieren, erhält dieser Host Ihren Schlüssel bei jedem Aufruf. Dieser Client lehnt eine einfache http://-Überschreibung außer für localhost/127.0.0.1/[::1] genau aus diesem Grund ab. Die gleiche Logik gilt für einen echten Schlüssel, der in eine beliebige Datei eingefügt wird: Wenn er jemals in git committet wird, ist das Rotieren des Schlüssels die einzige echte Lösung – die Git-Historie ist für immer. Ein späterer Commit, der die Zeile löscht, entfernt sie nicht aus der Historie des Repositorys, und jeder, der das Repo in der Zwischenzeit geklont hat, hat den alten Schlüssel noch.

Installation

npx -y @workel/mcp@0.4.0

Pinnen Sie die Version – 0.4.0 oben ist die aktuelle Version dieses Pakets; prüfen Sie npm view @workel/mcp version auf die neueste Version, bevor Sie sie pinnen. Die untenstehende ungepinnte Form ist nur zur Bequemlichkeit, gut für einen einmaligen manuellen Versuch, nicht für etwas, das die Konfiguration eines Agenten unbeaufsichtigt ausführt:

npx -y @workel/mcp

Umgebungsvariablen

doctor

Führen Sie npx -y @workel/mcp@0.4.0 doctor aus, wenn Ihr MCP-Client nur „server failed to start" ohne weitere Details meldet. Es führt dieselbe Startprüfung aus, die auch der Server selbst durchführt — Konfiguration laden, dann GET /me abfragen — und gibt einen Klartextbericht auf stdout aus, anstatt zu versuchen, das MCP-Protokoll zu sprechen:

base URL: https://api.workel.com/api/public/v1
workspace: Acme Inc
key: ci-key
scopes: read:projects, read:tasks
2 tools would register: workel_whoami, workel_list_projects
write budget: 59/60 remaining this minute

doctor startet niemals einen Transport und kommuniziert nie mit Ihrem MCP-Client — es ist ein eigenständiger Befehl, den Sie aus einem Terminal ausführen, und es beendet sich mit 0 bei Erfolg oder 1 bei jedem Fehler (fehlender/ungültiger WORKEL_API_KEY, eine nicht erreichbare API oder ein von der API abgelehnter Schlüssel). Anders als die einzeilige Zusammenfassung, die der Server bei einem normalen Start auf stderr ausgibt (die die Basis-URL weglässt, wenn sie der Standard ist), gibt doctor immer die effektive Basis-URL aus — auch wenn sie der Standard ist — denn ein Doctor-Lauf ist genau der Moment, in dem eine manipulierte WORKEL_API_BASE_URL sichtbar sein muss.

Tools

Diese Version registriert die folgenden Lese-Tools. workel_whoami benötigt überhaupt keinen Scope und funktioniert mit jedem gültigen Schlüssel; jedes andere Tool wird nur registriert, wenn die Scopes des Schlüssels (ermittelt über die GET /me-Abfrage oben) den aufgeführten Scope enthalten. Listen-Tools geben standardmäßig 25 Ergebnisse pro Aufruf zurück (maximal 50 — dieser Client begrenzt bewusst unterhalb der API-eigenen 100, siehe src/tools/conventions.ts) und blättern über ein undurchsichtiges cursor / next_cursor-Paar.

Schreib-Tools

Vier, und sie registrieren sich nur, wenn beide Bedingungen erfüllt sind: Der Schlüssel trägt den passenden write:*-Bereich und WORKEL_ENABLE_WRITES=true ist gesetzt. Nur eine davon allein registriert nichts, daher sieht eine schreibgeschützte Installation sie nie.

Kein Tool löscht etwas. workel_update_task ist mit destructiveHint: true annotiert, sodass ein Client, der Annotationen respektiert, vor jedem Aufruf eine Rückfrage stellt; die Lese-Tools sind als schreibgeschützt annotiert und laufen ohne eine solche.

Der gehostete Server unter mcp.workel.com läuft mit aktivierten Schreibrechten, sodass dort alle dreizehn Tools verfügbar sind.

Einschränkungen

replayed beweist keine Eindeutigkeit. Jeder Schreibvorgang, den die Tools dieses Servers ausführen würden, trägt einen Idempotency-Key, und der Idempotenzspeicher der Workel-API (24-Stunden-Aufbewahrung, auf den aufrufenden Schlüssel beschränkt) gibt für einen wiederholten Versuch mit demselben Schlüssel und demselben Anfragetext exakt dieselbe Antwort zurück — der zweite Versuch meldet replayed: true, und es wird nichts ein zweites Mal erstellt oder geändert.

replayed: false bedeutet, dass dieser spezielle Versuch tatsächlich ausgeführt wurde — es bedeutet nicht, dass kein Duplikat anderswo existiert. Insbesondere: Eine Fehlerantwort wird nie zwischengespeichert, sodass ein erneuter Versuch nach einem Fehler immer real erneut ausgeführt wird; der Idempotenzdatensatz läuft nach 24 Stunden ab, sodass ein sehr später erneuter Versuch real erneut ausgeführt wird; und der Speicher ist pro API-Schlüssel getrennt, sodass derselbe wörtliche Idempotency-Key-Wert, der unter einem anderen Schlüssel gesendet wird, niemals mit dem ersten kollidiert — und niemals vor einem Duplikat schützt, das durch den ersten erstellt wurde. Sofern ein Tool-Aufruf nicht explizit denselben Idempotenzschlüssel über zwei Versuche hinweg wiederverwendet, ist jeder Versuch aus Sicht des Servers ein wirklich unabhängiger Schreibvorgang.