aqua MCP

Überblick

Der aqua MCP-Server verbindet KI-Assistenten mit Ihrer aqua-Instanz. So können Sie aqua-Elemente in natürlicher Sprache suchen, lesen, erstellen und bearbeiten.

MCP (Model Context Protocol) ist ein offener Standard, über den KI-Assistenten externe Tools nutzen können. Der aqua MCP-Server funktioniert mit MCP-kompatiblen Assistenten wie Claude, Cursor oder GitHub Copilot in VS Code. Nach der Verbindung kann der Assistent mit Anforderungen, Testfällen, Testszenarien und Defekten arbeiten, Kommentare und Anhänge hinzufügen, Beziehungen zwischen Elementen verwalten und – für Administratoren – Benutzer und Lizenzen verwalten.

Alle Aktionen laufen mit den Berechtigungen des aqua-Benutzers, mit dem Sie sich verbinden. Der Assistent kann nichts sehen oder ändern, was dieser Benutzer in aqua nicht sehen oder ändern kann.

Download

Die aktuelle Version ist aqua MCP v2.6.0 und wird als MCP-Bundle-Datei (.mcpb) bereitgestellt. Claude Desktop installiert diese Datei direkt. Für andere Assistenten folgen Sie deren Anleitung zum Hinzufügen eines lokalen MCP-Servers.

aqua MCP v2.6.0 herunterladen (.mcpb)

Einrichtung in Claude Desktop

Die folgenden Schritte zeigen die Einrichtung in Claude Desktop. Andere MCP-kompatible Assistenten funktionieren ähnlich: Fügen Sie den aqua MCP-Server in den MCP-Einstellungen des Assistenten hinzu und geben Sie dieselben Verbindungsdaten ein.

Voraussetzungen

• Claude Desktop, installiert unter Windows oder macOS (Download)

• Ein aktives aqua-Benutzerkonto mit API-Zugriff und Zugriff auf die gewünschten Projekte

• Die aqua MCP-Datei .mcpb (siehe Download oben)

Erweiterung installieren

1. Laden Sie die Datei aqua v2.6.0.mcpb herunter.

2. Öffnen Sie Claude Desktop und gehen Sie zu Einstellungen > Erweiterungen.

3. Ziehen Sie die .mcpb-Datei in das Fenster „Erweiterungen“ oder öffnen Sie die Datei per Doppelklick mit Claude Desktop.

4. Klicken Sie im angezeigten Dialog auf Installieren.

Mit Ihrer aqua-Instanz verbinden

Nach der Installation fragt Claude Desktop nach den Verbindungsdaten:

Feld	Eingabe
aqua-URL	Die Adresse Ihrer aqua-Instanz, z. B. https://ihrefirma.aqua-cloud.io
Benutzername	Ihr aqua-Benutzername
Passwort	Ihr aqua-Passwort
Standardprojekt ID (optional)	Das Projekt, das der Assistent verwendet, wenn Sie kein anderes nennen. Leer lassen, um projektübergreifend zu suchen.

Klicken Sie auf Speichern und stellen Sie sicher, dass die Erweiterung aktiviert ist.

Hinweis: Ihre Zugangsdaten werden lokal von Claude Desktop gespeichert und nur für Aufrufe der aqua-API verwendet.

Verbindung testen

Starten Sie einen neuen Chat und fragen Sie:

Auf welche aqua-Projekte habe ich Zugriff?

Der Assistent sollte Ihre Projekte auflisten. Sie können das Arbeitsprojekt jederzeit wechseln, z. B. „Wechsle zum Projekt Webshop Release 3“.

Projekt-ID finden

Eine Projekt-ID benötigen Sie nur, wenn Sie ein Standardprojekt festlegen möchten. Die ID ist eine Zahl, z. B. 408.

In aqua. Öffnen Sie das Projekt im aqua Web-Client. Die Projekt-ID ist die Zahl in der URL in der Adresszeile Ihres Browsers.

Oder fragen Sie den Assistenten. Sobald der MCP-Server verbunden ist, fragen Sie:

Liste meine aqua-Projekte mit ihren IDs auf.

Der Assistent gibt alle Projekte, auf die Sie Zugriff haben, mit ihrer ID zurück. Kopieren Sie die ID des gewünschten Projekts und tragen Sie sie im Feld Standardprojekt ein.

Tipp: Im Chat können Sie jederzeit per Projektname wechseln, z. B. „Wechsle zum Projekt Login Page Project“.

Berechtigungen

Zwei Ebenen steuern, was der Assistent tun kann: Ihre aqua-Berechtigungen und die Tool-Berechtigungen in Ihrem KI-Assistenten.

aqua-Berechtigungen

Der MCP-Server handelt als der aqua-Benutzer, mit dem Sie sich verbunden haben. Der Assistent sieht nur die Projekte, Ordner und Elemente, auf die dieser Benutzer Zugriff hat, und kann nur Aktionen ausführen, die die Rolle des Benutzers erlaubt (siehe Rollen und Berechtigungen).

Tool-Gruppe	Erforderlich in aqua
Elemente, Kommentare, Historie und Anhänge lesen und durchsuchen	Lesezugriff auf das Projekt
Elemente, Testschritte, Testdaten, Kommentare und Beziehungen erstellen und bearbeiten	Bearbeitungsrechte für den Elementtyp in der Projektrolle
Status eines Elements ändern	Ein für die Rolle erlaubter Workflow-Übergang
Anhänge oder Kommentare löschen	Löschrechte in der Projektrolle
Benutzer- und Lizenzverwaltung	Serveradministrator

Tipp: Verbinden Sie sich für die tägliche Testarbeit mit einem normalen Projektbenutzer statt mit einem Administratorkonto. Die Verwaltungstools geben dann eine Berechtigungsfehlermeldung zurück, statt Änderungen vorzunehmen.

Tool-Berechtigungen in Ihrem KI-Assistenten

In den meisten Assistenten können Sie festlegen, welche Tools ohne Rückfrage ausgeführt werden dürfen. Gehen Sie in Claude Desktop zu Einstellungen > Erweiterungen > aqua und wählen Sie für jedes Tool eine dieser Optionen:

• Immer erlauben – Der Assistent führt das Tool ohne Rückfrage aus.

• Genehmigung erforderlich – Der Assistent fragt vor jedem Aufruf nach. Dies ist die Standardeinstellung.

• Blockiert – Der Assistent kann das Tool nicht verwenden.

Wir empfehlen, Lese-Tools zu erlauben, die Genehmigung für Tools, die Daten erstellen oder ändern, beizubehalten und die Benutzerverwaltungstools zu blockieren, wenn Sie sie nicht benötigen.

Verfügbare Tools

Version 2.6.0 enthält 44 Tools. Sie rufen sie nicht direkt auf: Der Assistent wählt anhand Ihrer Anfrage das passende Tool.

Bereich	Tools	Was der Assistent tun kann
Projekte	list-projects, get-current-project, set-current-project, get-statuses-for-project, list-field-ids	Projekte auflisten, Arbeitsprojekt wechseln, Status und Feldnamen abfragen
Suchen und lesen	global-search, list-items, get-item-details, get-item-history, get-item-relations	Elemente per Text oder Filter (Status, Zuständiger, Priorität, Sprint) finden und alle Details lesen. Die globale Suche durchsucht alle Projekte, wenn kein Standardprojekt festgelegt ist.
Erstellen und bearbeiten	create-item, update-item-fields, update-item-status, assign-item	Anforderungen, Testfälle, Testszenarien und Defekte (inkl. Unteranforderungen) erstellen, Felder aktualisieren, Status ändern, Benutzer zuweisen
Testfälle	get-test-steps, add-test-steps, get-test-data, set-test-data	Testschritte lesen und hinzufügen, Testdaten (Wertesätze) lesen und ersetzen
Beziehungen	add-item-relationship	Elemente verknüpfen, z. B. einen Testfall mit einer Anforderung oder einen Defekt mit einem Testfall
Kommentare	get-item-comments, add-comment-to-item, update-comment-on-item, delete-comment-on-item	Diskussionskommentare lesen und schreiben
Anhänge	list-attachments, download-attachment, upload-attachment, delete-attachment	Mit Anhängen von Elementen arbeiten
Benutzer und Lizenzen (Admin)	list-users, get-user, create-user, update-user, activate-user, deactivate-user, reset-user-password, set-user-password, set-server-administrator, list-roles, list-project-users, assign-user-to-project, unassign-user-from-project, list-licenses, list-assigned-licenses, assign-user-license, remove-user-license	Benutzer, Projektzuweisungen, Rollen und Lizenzen verwalten
Eingebettete Bilder	get-item-details (Parameter downloadImages)	Bilder aus Rich-Text-Beschreibungen herunterladen, damit der Assistent sie ansehen kann
Integrierte Anleitung	aqua-guide (MCP-Prompt)	Zeigt dem Assistenten, wie er die aqua-Tools effektiv nutzt

Warnung: set-test-data ersetzt alle vorhandenen Testdaten eines Testfalls. Wertesätze, die nicht in der Anfrage enthalten sind, werden gelöscht.

Anwendungsfälle

Die folgenden Beispiele zeigen typische Prompts. Der Assistent kombiniert mehrere Tools pro Anfrage, Sie können Ihr Ziel also in natürlicher Sprache beschreiben.

Testfälle aus einer Anforderung generieren

Lies die Anforderung RQ-1042 und erstelle 5 Testfälle, die ihre Akzeptanzkriterien abdecken. Füge jedem Testfall Testschritte hinzu und verknüpfe sie mit der Anforderung.

Abdeckungslücken finden

Liste alle Anforderungen im Status "Freigegeben" auf, die keinen verknüpften Testfall haben.

Defekt aus einem Testergebnis oder Fehlerlog erstellen

Erstelle einen Defekt für diesen Fehler, hänge das Log als Anhang an und verknüpfe ihn mit dem Testfall TC-318: <Log einfügen>

Testdaten generieren

Erstelle Testdaten für TC-205 mit 10 Wertesätzen für gültige und ungültige IBANs, E-Mail-Adressen und Postleitzahlen.

Statusberichte und tägliche Übersichten

Fasse alle offenen Defekte mit Priorität Hoch zusammen, gruppiert nach Zuständigem.

Massenänderungen

Setze alle Testfälle im Ordner "Checkout", die noch im Status "Entwurf" sind, auf "Bereit zur Prüfvfung" und weise sie Anna zu.

Bestehende Elemente prüfen und verbessern

Prüfe die Testfälle TC-100 bis TC-120 auf fehlende erwartete Ergebnisse und schlage Verbesserungen vor.

Benutzer-Onboarding (Administratoren)

Lege einen Benutzer für [e-mail] an, weise ihn dem Projekt "Mobile App" mit der Rolle Tester zu und gib ihm eine Named-Lizenz.

Fehlerbehebung

Problem	Lösung
Der Assistent nutzt die aqua-Tools nicht	Prüfen Sie, ob der aqua MCP-Server in den Einstellungen Ihres Assistenten aktiviert ist (in Claude Desktop: Einstellungen > Erweiterungen) und ob seine Tools für den Chat eingeschaltet sind. Starten Sie den Assistenten nach der Installation neu.
Anmelde- oder Verbindungsfehler	Prüfen Sie die aqua-URL (ohne angehängten Pfad), den Benutzernamen und das Passwort. Konten, die sich nur per SSO anmelden, benötigen eventuell ein separates aqua-Passwort.
Elemente oder Projekte fehlen	Der verbundene Benutzer hat keinen Zugriff darauf. Prüfen Sie die Projektzuweisung und Rolle des Benutzers in aqua.
„Keine Berechtigung“ beim Erstellen oder Ändern von Elementen	Die Rolle des Benutzers erlaubt diese Aktion nicht, oder der Workflow erlaubt den Statusübergang nicht.
Der Assistent arbeitet im falschen Projekt	Bitten Sie den Assistenten, das Projekt zu wechseln, oder nennen Sie das Projekt in Ihrem Prompt.

Kommen Sie nicht weiter? Kontaktieren Sie unseren Support.