Mit Claude Code verbinden

Dies ist die zentrale Integration von Almirant. Wenn du deine IDE über MCP (Model Context Protocol) mit Almirant verbindest, kann die KI deine Aufgaben lesen, Code implementieren, Work Items zwischen Spalten verschieben und Pull Requests erstellen, ohne den Editor zu verlassen.

Was MCP ist und warum du es verbinden solltest

MCP (Model Context Protocol) ist ein offenes Protokoll, das KI-Tools wie Claude Code oder Cursor die bidirektionale Kommunikation mit externen Diensten ermöglicht. Nach dem Verbinden von Almirant über MCP:

• liest die KI deine Work Items, Boards und Sprints direkt
• aktualisiert die KI beim Implementieren den Aufgabenstatus
• erstellt die KI neue Work Items, wenn sie Teilaufgaben erkennt
• greift die KI auf den Projektkontext zu (Tech Stack, Beschreibung, Ziele)

Voraussetzungen

Bevor du startest, stelle sicher, dass du Folgendes hast:

• Claude Code installiert: Installationsanleitung
• Ein Projekt in Almirant: Dein erstes Projekt erstellen
• Einen Almirant-API Key: Dieser wird im nächsten Schritt erstellt

Schritt 1: Einen API Key erstellen

1. Öffne in Almirant Settings über das Seitenmenü
2. Navigiere zum Bereich API Keys
3. Klicke auf API Key erstellen
4. Gib ihm einen aussagekräftigen Namen, beispielsweise „Claude Code - Arbeits-Laptop“
5. Kopiere den erzeugten API Key

API Key speichern

Der API Key wird beim Erstellen nur einmal angezeigt. Kopiere ihn und bewahre ihn sicher auf. Wenn du ihn verlierst, musst du einen neuen erstellen.

Schritt 2: Die Project ID abrufen

Du benötigst die ID des Projekts, mit dem du die KI verbinden möchtest. Es gibt zwei Möglichkeiten:

Option A: Über die URL

Öffne dein Projekt in Almirant und kopiere die UUID aus der Browser-URL:

https://almirant.ai/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                               └──────────── dies ist deine projectId ────────────┘

Option B: Über das MCP-Tool

Wenn du die Verbindung ohne projectId konfigurierst, kannst du das Tool list_projects verwenden, um alle Projekte und ihre IDs zu sehen.

Schritt 3: .mcp.json konfigurieren

Erstelle oder bearbeite die Datei .mcp.json im Stammverzeichnis deines Repositorys:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<your-project-id>",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Ersetze die Werte:

Platzhalter	Wert
<your-project-id>	Die in Schritt 2 erhaltene Projekt-UUID
<your-api-key>	Der in Schritt 1 erzeugte API Key

Beispiel mit echten Werten:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "headers": {
        "Authorization": "Bearer alm_k7x9m2p4q8r1..."
      }
    }
  }
}

Datei .mcp.json im Repository

Du kannst .mcp.json in dein Repository aufnehmen, damit das gesamte Team dieselbe Konfiguration teilt. Verwende dann für den API Key eine Umgebungsvariable, statt ihn direkt in die Datei einzutragen.

Schritt 4: Die Verbindung prüfen

Öffne Claude Code in deinem Terminal und prüfe die Verbindung:

1. Starte Claude Code im Projektverzeichnis, in dem du .mcp.json erstellt hast
2. Bitte Claude, deine Projekte aufzulisten:

> Liste meine Almirant-Projekte auf

Wenn die Verbindung korrekt ist, antwortet Claude mit der Projektliste. Wenn projectId konfiguriert ist, werden die Details des jeweiligen Projekts angezeigt.

Verfügbare MCP-Tools nach der Verbindung:

Tool	Beschreibung
list_projects	Listet verfügbare Projekte auf
list_boards	Listet die Boards des Projekts auf
list_work_items	Listet Work Items mit Filtern auf
create_work_item	Erstellt ein neues Work Item
update_work_item	Aktualisiert ein vorhandenes Work Item
list_sprints	Listet die Sprints des Projekts auf

Konfiguration für Cursor

Die Konfiguration für Cursor ist identisch. Der Unterschied besteht nur im Speicherort der Konfigurationsdatei.

Cursor verwendet dasselbe .mcp.json-Format. Lege die Datei im Stammverzeichnis deines Projekts oder gemäß der Dokumentation deiner Version in der globalen Cursor-Konfiguration ab.

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<your-project-id>",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Fehlerbehebung

Die Verbindung schlägt fehl oder antwortet nicht

1. URL prüfen: Stelle sicher, dass die URL https://api.almirant.ai/mcp lautet, nicht https://almirant.ai/mcp
2. API Key prüfen: Erstelle einen neuen, wenn du dir beim aktuellen nicht sicher bist
3. JSON-Format prüfen: Ein Syntaxfehler in .mcp.json verhindert die Verbindung

„Unauthorized“ oder „Invalid API Key“

• Der API Key wurde möglicherweise widerrufen oder ist abgelaufen
• Gehe in Almirant zu Settings > API Keys und erstelle einen neuen
• Aktualisiere den Wert in deiner .mcp.json

„Project not found“

• Prüfe, ob projectId in der URL korrekt ist
• Stelle sicher, dass dein Konto Zugriff auf das Projekt hat
• Teste ohne projectId und verwende list_projects, um verfügbare IDs anzuzeigen

Claude Code erkennt den MCP-Server nicht

• Stelle sicher, dass .mcp.json im Stammverzeichnis liegt, aus dem du Claude Code ausführst
• Starte Claude Code nach dem Erstellen oder Ändern der Datei neu
• Stelle sicher, dass das JSON gültig ist (keine zusätzlichen Kommas, korrekte Anführungszeichen)

---

Nächster Schritt: Dein erster KI-Workflow: Implementiere eine vollständige Aufgabe mit KI aus deiner IDE.