MCP Atlassian

Model Context Protocol (MCP)-Server für Atlassian-Produkte (Confluence und Jira). Diese Integration unterstützt sowohl Confluence & Jira Cloud- als auch Server-/Data Center-Bereitstellungen.

Beispielverwendung

Bitten Sie Ihren KI-Assistenten:

• 📝 Automatische Jira-Updates – „Aktualisieren Sie Jira anhand unserer Besprechungsnotizen“

• 🔍 KI-gestützte Confluence-Suche – „Finden Sie unseren OKR-Leitfaden in Confluence und fassen Sie ihn zusammen“

• 🐛 Intelligente Jira-Problemfilterung – „Zeigen Sie mir dringende Fehler im PROJ-Projekt von letzter Woche“

• 📄 Inhaltserstellung und -verwaltung – „Erstellen Sie ein technisches Designdokument für die Funktion XYZ“

Funktionsdemo

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

Kompatibilität

Related MCP server: MCP Atlassian

Kurzanleitung

🔐 1. Authentifizierungs-Setup

MCP Atlassian unterstützt drei Authentifizierungsmethoden:

A. API-Token-Authentifizierung (Cloud)

1. Gehen Sie zu https://id.atlassian.com/manage-profile/security/api-tokens

2. Klicken Sie auf API-Token erstellen und benennen Sie es

3. Kopieren Sie das Token sofort

B. Persönlicher Zugriffstoken (Server/Rechenzentrum)

1. Gehen Sie zu Ihrem Profil (Avatar) → Profil → Persönliche Zugriffstoken

2. Klicken Sie auf „Token erstellen“ , benennen Sie es und legen Sie das Ablaufdatum fest

3. Kopieren Sie das Token sofort

C. OAuth 2.0-Authentifizierung (Cloud)

1. Zur Atlassian Developer Console

2. Erstellen Sie eine App zur „OAuth 2.0 (3LO)-Integration“

3. Konfigurieren Sie Berechtigungen (Bereiche) für Jira/Confluence

4. Rückruf-URL festlegen (z. http://localhost:8080/callback )

5. Führen Sie den Setup-Assistenten aus:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

6. Folgen Sie den Anweisungen für Client ID , Secret , URI und Scope

7. Vollständige Browserautorisierung

8. Fügen Sie die erhaltenen Anmeldeinformationen zur .env oder IDE-Konfiguration hinzu:

   • ATLASSIAN_OAUTH_CLOUD_ID (vom Assistenten)

   • ATLASSIAN_OAUTH_CLIENT_ID

   • ATLASSIAN_OAUTH_CLIENT_SECRET

   • ATLASSIAN_OAUTH_REDIRECT_URI

   • ATLASSIAN_OAUTH_SCOPE

[!WICHTIG] offline_access in den Bereich für dauerhafte Authentifizierung einschließen (z. B. read:jira-work write:jira-work offline_access )

📦 2. Installation

MCP Atlassian wird als Docker-Image bereitgestellt. Dies ist die empfohlene Ausführungsmethode für den Server, insbesondere für die IDE-Integration. Stellen Sie sicher, dass Docker installiert ist.

# Pull Pre-built Image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

🛠️ IDE-Integration

MCP Atlassian ist für die Verwendung mit KI-Assistenten durch IDE-Integration konzipiert.

[!TIP] Für Claude Desktop : Suchen und bearbeiten Sie die Konfigurationsdatei direkt:

• Windows : %APPDATA%\Claude\claude_desktop_config.json

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux : ~/.config/Claude/claude_desktop_config.json

Für Cursor : Öffnen Sie Einstellungen → MCP → + Neuen globalen MCP-Server hinzufügen

⚙️ Konfigurationsmethoden

Es gibt zwei Hauptansätze zum Konfigurieren des Docker-Containers:

1. Direktes Übergeben von Variablen (siehe Beispiele unten)

2. Verwenden einer Umgebungsdatei mit dem Flag --env-file (in einklappbaren Abschnitten angezeigt)

[!NOTE] Zu den gängigen Umgebungsvariablen gehören:

• CONFLUENCE_SPACES_FILTER : Filtern nach Space-Schlüsseln (z. B. „DEV, TEAM, DOC“)

• JIRA_PROJECTS_FILTER : Filtern nach Projektschlüsseln (z. B. „PROJ,DEV,SUPPORT“)

• READ_ONLY_MODE : Auf „true“ setzen, um Schreibvorgänge zu deaktivieren

• MCP_VERBOSE : Auf „true“ setzen für detailliertere Protokollierung

• ENABLED_TOOLS : Kommagetrennte Liste der zu aktivierenden Toolnamen (z. B. „confluence_search,jira_get_issue“)

Alle verfügbaren Optionen finden Sie in der Datei .env.example .

📝 Konfigurationsbeispiele

Methode 1 (Direkte Übergabe von Variablen):

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Verwenden Sie für Server-/Data-Center-Bereitstellungen die direkte Variablenübergabe:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat",
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

[!NOTE] Setzen Sie CONFLUENCE_SSL_VERIFY und JIRA_SSL_VERIFY nur dann auf „false“, wenn Sie über selbstsignierte Zertifikate verfügen.

Dieses Beispiel zeigt, wie Sie mcp-atlassian in Ihrer IDE (z. B. Cursor oder Claude Desktop) konfigurieren, wenn Sie OAuth 2.0 für Atlassian Cloud verwenden. Stellen Sie sicher, dass Sie zuerst den OAuth-Setup-Assistenten abgeschlossen haben.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest",
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

[!NOTIZ]

• ATLASSIAN_OAUTH_CLOUD_ID wird aus der Ausgabe des Assistenten --oauth-setup abgerufen.

• Andere ATLASSIAN_OAUTH_* Variablen sind diejenigen, die Sie für Ihre OAuth-App in der Atlassian Developer Console konfiguriert haben (und als Eingabe für den Setup-Assistenten verwendet haben).

• JIRA_URL und CONFLUENCE_URL für Ihre Cloud-Instanzen werden weiterhin benötigt.

MCP Atlassian unterstützt das Routing von API-Anfragen über Standard-HTTP/HTTPS/SOCKS-Proxys. Konfigurieren Sie mithilfe von Umgebungsvariablen:

• Unterstützt Standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY , SOCKS_PROXY .

• Es sind dienstspezifische Überschreibungen verfügbar (z. B. JIRA_HTTPS_PROXY , CONFLUENCE_NO_PROXY ).

• Dienstspezifische Variablen überschreiben globale Variablen für diesen Dienst.

Fügen Sie die relevanten Proxy-Variablen zu den Abschnitten args (mit -e ) und env Ihrer MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... existing Confluence/Jira vars",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... existing Confluence/Jira vars": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

Anmeldeinformationen in Proxy-URLs werden in Protokollen maskiert. Wenn Sie NO_PROXY festlegen, wird dies bei Anfragen an übereinstimmende Hosts berücksichtigt.

Nur für Confluence Cloud:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

Verwenden Sie für Confluence Server/DC:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

Nur für Jira Cloud:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Verwenden Sie für Jira Server/DC:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

👥 HTTP-Transportkonfiguration

Anstatt stdio zu verwenden, können Sie den Server als dauerhaften HTTP-Dienst ausführen, indem Sie Folgendes verwenden:

• sse -Transport (Server-Sent Events) am /sse Endpunkt

• streamable-http Transport am /mcp Endpunkt

Beide Transporttypen unterstützen die Einzelbenutzer- und Mehrbenutzerauthentifizierung:

Authentifizierungsoptionen:

• Einzelbenutzer : Verwenden Sie die über Umgebungsvariablen konfigurierte Authentifizierung auf Serverebene

• Mehrbenutzer : Jeder Benutzer stellt seine eigene Authentifizierung bereit:

  • Cloud: OAuth 2.0-Bearer-Token

  • Server/Rechenzentrum: Persönliche Zugriffstoken (PATs)

1. Starten Sie den Server mit dem von Ihnen gewählten Transportmittel:

   # For SSE transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport sse --port 9000 -vv
   
   # OR for streamable-http transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

2. Konfigurieren Sie Ihre IDE (Beispiel für einen Einzelbenutzer):

   SSE-Transportbeispiel:

   {
     "mcpServers": {
       "mcp-atlassian-http": {
         "url": "http://localhost:9000/sse"
       }
     }
   }

   Beispiel für Streamable-HTTP-Transport:

   {
     "mcpServers": {
       "mcp-atlassian-service": {
         "url": "http://localhost:9000/mcp"
       }
     }
   }

Hier ist ein vollständiges Beispiel für die Einrichtung einer Mehrbenutzerauthentifizierung mit streambarem HTTP-Transport:

1. Führen Sie zunächst den OAuth-Setup-Assistenten aus, um die OAuth-Anmeldeinformationen des Servers zu konfigurieren:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

2. Starten Sie den Server mit streamable-HTTP-Transport:

   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

3. Konfigurieren Sie die MCP-Einstellungen Ihrer IDE:

Wählen Sie die entsprechende Autorisierungsmethode für Ihre Atlassian-Bereitstellung:

• Cloud (OAuth 2.0): Verwenden Sie dies, wenn sich Ihre Organisation in der Atlassian Cloud befindet und Sie für jeden Benutzer ein OAuth-Zugriffstoken haben.

• Server/Rechenzentrum (PAT): Verwenden Sie dies, wenn Sie sich auf einem Atlassian-Server oder -Rechenzentrum befinden und jeder Benutzer über ein persönliches Zugriffstoken (PAT) verfügt.

Cloud (OAuth 2.0) Beispiel:

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

Server/Rechenzentrum (PAT) Beispiel:

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

4. Erforderliche Umgebungsvariablen in .env :

   JIRA_URL=https://your-company.atlassian.net
   CONFLUENCE_URL=https://your-company.atlassian.net/wiki
   ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id
   ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret
   ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
   ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access
   ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

[!NOTIZ]

• Der Server sollte eine eigene Fallback-Authentifizierung konfiguriert haben (z. B. über Umgebungsvariablen für API-Token, PAT oder ein eigenes OAuth-Setup mit --oauth-setup). Dies wird verwendet, wenn eine Anfrage keine benutzerspezifische Authentifizierung enthält.

• OAuth : Jeder Benutzer benötigt sein eigenes OAuth-Zugriffstoken von Ihrer Atlassian OAuth-App.

• PAT : Jeder Benutzer stellt sein eigenes persönliches Zugriffstoken bereit.

• Der Server verwendet das Token des Benutzers für API-Aufrufe, sofern es bereitgestellt wird. Andernfalls greift er auf die Serverauthentifizierung zurück.

• Benutzertoken sollten über geeignete Bereiche für die erforderlichen Vorgänge verfügen

Werkzeuge

Wichtige Werkzeuge

Jira-Tools

• jira_get_issue : Details zu einem bestimmten Problem abrufen

• jira_search : Probleme mit JQL suchen

• jira_create_issue : Ein neues Problem erstellen

• jira_update_issue : Ein bestehendes Problem aktualisieren

• jira_transition_issue : Überführen eines Problems in einen neuen Status

• jira_add_comment : Einen Kommentar zu einem Problem hinzufügen

Confluence-Tools

• confluence_search : Durchsuchen Sie Confluence-Inhalte mit CQL

• confluence_get_page : Inhalt einer bestimmten Seite abrufen

• confluence_create_page : Eine neue Seite erstellen

• confluence_update_page : Eine vorhandene Seite aktualisieren

*Tool nur in Jira Cloud verfügbar

Werkzeugfilterung und Zugriffskontrolle

Der Server bietet zwei Möglichkeiten zur Steuerung des Toolzugriffs:

1. Werkzeugfilterung : Verwenden Sie das Flag --enabled-tools oder die Umgebungsvariable ENABLED_TOOLS , um anzugeben, welche Werkzeuge verfügbar sein sollen:

   # Via environment variable
   ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
   
   # Or via command line flag
   docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

2. Lese-/Schreibsteuerung : Tools werden als Lese- oder Schreibvorgänge kategorisiert. Wenn READ_ONLY_MODE aktiviert ist, sind unabhängig von der Einstellung ENABLED_TOOLS nur Lesevorgänge verfügbar.

Fehlerbehebung und Debugging

Häufige Probleme

• Authentifizierungsfehler :

  • Für die Cloud: Überprüfen Sie Ihre API-Token (nicht Ihr Kontopasswort)

  • Für Server/Rechenzentrum: Überprüfen Sie, ob Ihr persönliches Zugriffstoken gültig und nicht abgelaufen ist

  • Für ältere Confluence-Server: Einige ältere Versionen erfordern eine grundlegende Authentifizierung mit CONFLUENCE_USERNAME und CONFLUENCE_API_TOKEN (wobei Token Ihr Passwort ist).

• Probleme mit SSL-Zertifikaten : Wenn Sie Server/Data Center verwenden und SSL-Fehler auftreten, setzen Sie CONFLUENCE_SSL_VERIFY=false oder JIRA_SSL_VERIFY=false

• Berechtigungsfehler : Stellen Sie sicher, dass Ihr Atlassian-Konto über ausreichende Berechtigungen für den Zugriff auf die Bereiche/Projekte verfügt

Debugging-Tools

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

Sicherheit

• Geben Sie niemals API-Token weiter

• Halten Sie .env-Dateien sicher und privat

• Best Practices finden Sie unter SECURITY.md

Beitragen

Wir freuen uns über Beiträge zu MCP Atlassian! Wenn Sie mitmachen möchten:

1. Ausführliche Anweisungen zur Einrichtung der Entwicklung finden Sie in unserem CONTRIBUTING.md- Handbuch.

2. Nehmen Sie Änderungen vor und senden Sie eine Pull-Anfrage.

Wir verwenden Pre-Commit-Hooks für die Codequalität und folgen der semantischen Versionierung für Releases.

Lizenz

Lizenziert unter MIT (siehe LICENSE- Datei). Dies ist kein offizielles Atlassian-Produkt.