Confluence MCP-Server

Model Context Protocol (MCP)-Server für die Atlassian Confluence-Integration mit Claude Code.

Funktionen

• 🔍 Suche in Confluence-Seiten mittels CQL (Confluence Query Language)

• 📄 Lesen von Seiten nach ID oder Titel

• ✏️ Erstellen und Aktualisieren von Seiten

• 🏷️ Verwalten von Labels und Metadaten

• 📁 Auflisten von Bereichen und Anhängen

• 🔐 Sichere Basis-Authentifizierung mit API-Tokens

Related MCP server: mcp-confluence

Installation

Voraussetzungen

• Node.js 18+ und npm

• Atlassian Confluence Cloud-Konto

• API-Token (siehe Konfiguration unten)

Einrichtung

git clone https://github.com/gkrauchunas-arlo/confluence-mcp.git
cd confluence-mcp
npm install

Konfiguration

1. Kopieren Sie .env.example nach .env:

   cp .env.example .env

2. Tragen Sie Ihre Atlassian-Anmeldedaten in .env ein:

   ATLASSIAN_SITE=your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-token

Einen API-Token erhalten:

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

2. Klicken Sie auf "Create API token"

3. Geben Sie ihm einen Namen (z. B. "Claude Code MCP") und kopieren Sie den Token in die .env-Datei

Testen

# Test Confluence API connectivity
node test-confluence.js

# Test MCP protocol (via stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Verbindung mit Claude Code herstellen

Option 1: CLI (Empfohlen)

claude mcp add --transport stdio confluence \
  --env ATLASSIAN_SITE="your-domain.atlassian.net" \
  --env ATLASSIAN_EMAIL="your-email@example.com" \
  --env ATLASSIAN_API_TOKEN="your-token" \
  -- node /absolute/path/to/confluence-mcp/index.js

Ersetzen Sie /absolute/path/to/ durch Ihren tatsächlichen Installationspfad (z. B. /home/username/confluence-mcp).

Option 2: Konfigurationsdatei

Fügen Sie dies Ihrer Claude Code MCP-Konfigurationsdatei hinzu:

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/absolute/path/to/confluence-mcp/index.js"],
      "env": {
        "ATLASSIAN_SITE": "your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-token"
      }
    }
  }
}

Speicherorte der Konfigurationsdatei:

• Linux: ~/.config/claude-code/mcp_servers.json oder ~/.claude/config/mcp_servers.json

• macOS: ~/Library/Application Support/claude-code/mcp_servers.json

• Windows: %APPDATA%\claude-code\mcp_servers.json

Starten Sie nach der Konfiguration Claude Code neu, um den MCP-Server zu aktivieren.

Verfügbare Tools

Suche & Navigation

• confluence_search - CQL-Suche über alle Inhalte

  • Parameter: query (Zeichenkette), limit (Zahl, optional), spaceKey (Zeichenkette, optional)

  • Beispiel: Suche nach Seiten mit "API" im Titel innerhalb eines bestimmten Bereichs

• confluence_list_spaces - Alle Bereiche auflisten

  • Parameter: limit (Zahl, optional, Standard: 25)

  • Rückgabe: Liste aller Confluence-Bereiche, auf die Ihr Konto Zugriff hat

Inhalte lesen

• confluence_get_page - Seite nach ID abrufen

  • Parameter: pageId (Zeichenkette)

  • Rückgabe: Vollständige Seitendaten inklusive Inhalt, Version und Metadaten

• confluence_get_page_by_title - Seite nach Titel und Bereich finden

  • Parameter: title (Zeichenkette), spaceKey (Zeichenkette)

  • Rückgabe: Seite, die exakt mit dem Titel im angegebenen Bereich übereinstimmt

• confluence_get_space - Bereichsinformationen abrufen

  • Parameter: spaceKey (Zeichenkette)

  • Rückgabe: Bereichs-Metadaten und Konfiguration

• confluence_get_attachments - Seitenanhänge auflisten

  • Parameter: pageId (Zeichenkette)

  • Rückgabe: Liste aller Anhänge auf einer Seite

Erstellen & Bearbeiten

• confluence_create_page - Neue Seite erstellen

  • Parameter: title (Zeichenkette), spaceKey (Zeichenkette), content (HTML-Zeichenkette), parentId (Zeichenkette, optional)

  • Erstellt eine neue Seite im angegebenen Bereich, optional als Unterseite einer anderen Seite

• confluence_update_page - Bestehende Seite aktualisieren

  • Parameter: pageId (Zeichenkette), title (Zeichenkette), content (HTML-Zeichenkette), version (Zahl)

  • Aktualisiert eine Seite mit neuem Inhalt. Die Versionsnummer muss mit der aktuellen Seitenversion übereinstimmen.

Metadaten

• confluence_add_labels - Labels zu einer Seite hinzufügen

  • Parameter: pageId (Zeichenkette), labels (Array von Zeichenketten)

  • Fügt einer Seite ein oder mehrere Labels/Tags zur Kategorisierung hinzu

Anwendungsbeispiele

Sobald die Verbindung zu Claude Code hergestellt ist, können Sie natürliche Sprache verwenden, um mit Confluence zu interagieren:

Nach Seiten suchen

Find all pages about "API documentation" in Confluence

Eine Seite lesen

Read the contents of Confluence page with ID 12345

Eine neue Seite erstellen

Create a new page in the DEV space titled "API Guidelines" with this content:
<h1>API Guidelines</h1>
<p>This document describes our API design principles.</p>

Eine Seite aktualisieren

Update Confluence page 12345 to add a new section about authentication

Labels hinzufügen

Add labels "documentation" and "api" to Confluence page 12345

CQL-Abfragebeispiele

Das confluence_search-Tool unterstützt die Confluence Query Language (CQL):

type=page AND title~"API"
type=page AND space=DEV
type=page ORDER BY lastmodified DESC
type=page AND label=documentation
type=page AND creator=currentUser()

API-Referenz

Dieser MCP-Server verwendet die Confluence REST API:

• Basis-URL: https://{site}.atlassian.net/wiki/rest/api

• Authentifizierung: Basis-Authentifizierung mit E-Mail + API-Token

• API-Version: Cloud REST API (stabil)

• Vollständige API-Dokumentation

Fehlerbehebung

"Authentication failed"

• Überprüfen Sie Ihre E-Mail und Ihren API-Token in .env

• Stellen Sie sicher, dass der Token nicht abgelaufen ist (API-Tokens laufen nicht ab, können aber widerrufen werden)

• Überprüfen Sie, ob Sie einen API-Token verwenden und nicht Ihr Atlassian-Kontopasswort

"MCP tools not showing up"

• Starten Sie Claude Code vollständig neu (schließen und erneut öffnen)

• Überprüfen Sie die Server-Logs auf Fehler, indem Sie node index.js direkt ausführen

• Überprüfen Sie die Konfiguration mit claude mcp list

• Stellen Sie sicher, dass der vollständige absolute Pfad in der Konfiguration verwendet wird

"Permission denied"-Fehler

• Stellen Sie sicher, dass Ihr Atlassian-Konto Zugriff auf die angeforderten Bereiche/Seiten hat

• Einige Vorgänge erfordern spezifische Berechtigungen (z. B. Bereichsadministrator zum Erstellen von Seiten)

• Überprüfen Sie die Bereichsberechtigungen in der Confluence-Weboberfläche

"Page version conflict"

• Beim Aktualisieren einer Seite müssen Sie die aktuelle Versionsnummer angeben

• Rufen Sie die aktuelle Version zuerst mit confluence_get_page ab

• Der Server erhöht die Version automatisch um 1

Inhaltsformat

Confluence-Seiten verwenden das Storage Format (HTML mit Confluence-Makros). Für einfache Seiten funktioniert Standard-HTML:

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Bullet point 1</li>
  <li>Bullet point 2</li>
</ul>
<pre><code>Code block</code></pre>

Für fortgeschrittene Funktionen siehe die Dokumentation zum Confluence Storage Format.

Architektur

Basiert auf:

• @modelcontextprotocol/sdk - MCP-Protokollimplementierung

• axios - HTTP-Client für die Confluence REST API

• dotenv - Konfigurationsmanagement

Der Server läuft als stdio-basierter MCP-Server und kommuniziert mit Claude Code über JSON-RPC 2.0 mittels Standard-Ein-/Ausgabe.

Entwicklung

Projektstruktur

confluence-mcp/
├── index.js              # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── test-confluence.js    # Confluence API connectivity tests
├── test-mcp.js           # MCP protocol tests (WIP)
├── .env.example          # Example configuration
├── .env                  # Your configuration (gitignored)
└── README.md             # This file

Tests ausführen

# Test Confluence API directly
node test-confluence.js

# Test MCP server via stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Mitwirken

Beiträge sind willkommen! Bitte:

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Führen Sie Ihre Änderungen mit Tests durch

4. Committen Sie Ihre Änderungen (git commit -m 'feat: add amazing feature')

5. Pushen Sie auf den Branch (git push origin feature/amazing-feature)

6. Öffnen Sie einen Pull Request

Bekannte Einschränkungen

1. Anhang-Uploads - Noch nicht implementiert (erfordert multipart/form-data-Kodierung)

2. Rich-Text-Formatierung - Nur einfaches HTML wird unterstützt, Confluence-Makros können komplex sein

3. Paginierung - Große Ergebnismengen sind durch den limit-Parameter begrenzt

4. Berechtigungen - Die API gibt nur Inhalte zurück, auf die der authentifizierte Benutzer Zugriff hat

Lizenz

ISC

Danksagungen

• Architektur inspiriert von rovo-mcp

• Erstellt für Claude Code

• Verwendet das Model Context Protocol

Support

• Probleme: https://github.com/gkrauchunas-arlo/confluence-mcp/issues

• Atlassian API-Dokumentation: https://developer.atlassian.com/cloud/confluence/rest/

• MCP-Spezifikation: https://modelcontextprotocol.io/specification

Erstellt von: gkrauchunas-arlo Status: Stabil v1.0.0 - Alle Kernfunktionen implementiert und getestet