¶ Wiki.js MCP Server
¶ Inhaltsverzeichnis
- Was ist ein MCP-Server?
- Was kann der Wiki.js MCP Server?
- Voraussetzungen
- Installation
- Verfügbare Tools
- Verwendungsbeispiele
- Workflow: Plugin-Entwicklung → Wiki-Dokumentation
- Troubleshooting
- Technische Details
- Best Practices
¶ Was ist ein MCP-Server?
Das Model Context Protocol (MCP) ist ein offenes Protokoll, das es KI-Assistenten wie Claude ermöglicht, mit externen Tools und Diensten zu interagieren. Ein MCP-Server stellt eine Sammlung von "Tools" (Funktionen) bereit, die Claude während eines Gesprächs aufrufen kann.
Vorteile von MCP:
- 🔌 Erweiterbar - Füge Claude neue Fähigkeiten hinzu, ohne den Code zu ändern
- 🔒 Sicher - Volle Kontrolle über Berechtigungen und Zugriff
- 🚀 Automatisierung - Wiederkehrende Aufgaben direkt aus Claude erledigen
- 🎯 Kontext-bewusst - Claude kann auf deine Tools zugreifen, während du entwickelst
¶ Beispiel-Workflow
Ohne MCP-Server:
- Du entwickelst ein Plugin in Claude Code
- Du schreibst manuell die README.md
- Du loggst dich in Wiki.js ein
- Du kopierst/pastest Dokumentation manuell
- Du formatierst alles per Hand
Mit MCP-Server:
- Du entwickelst ein Plugin in Claude Code
- Du sagst: "Erstelle eine ausführliche Wiki-Seite dafür"
- ✅ Claude erstellt automatisch die Wiki-Seite mit Struktur, Code-Beispielen und Dokumentation
¶ Was kann der Wiki.js MCP Server?
Dieser MCP-Server ermöglicht Claude, direkt mit deiner Wiki.js-Instanz zu interagieren:
¶ Features
- ✅ Seiten erstellen - Neue Wiki-Seiten mit Markdown oder HTML Content
- ✅ Seiten aktualisieren - Bestehende Seiten bearbeiten (Inhalt, Titel, Beschreibung, Tags)
- ✅ Seiten abrufen - Seiten per ID oder Pfad laden
- ✅ Seiten auflisten - Alle Seiten mit optionaler Sprach-Filterung
- ✅ Seiten suchen - Volltext-Suche über alle Wiki-Inhalte
- ✅ Seiten löschen - Seiten aus dem Wiki entfernen
- ✅ Seiten verschieben - Content reorganisieren durch Pfad-Änderung
¶ Typische Anwendungsfälle
1. Automatische Dokumentation nach Plugin-Entwicklung
Du: "Ich habe gerade das Ticket-Merge-Plugin fertig entwickelt.
Erstelle eine ausführliche technische Dokumentation in Wiki.js."
Claude: *Analysiert den Code, die Architektur und API*
*Erstellt automatisch eine strukturierte Wiki-Seite mit:*
- Technischer Übersicht
- Architektur-Diagrammen
- API-Dokumentation
- Code-Beispielen
- Troubleshooting-Guide
2. Wissensmanagement während der Entwicklung
Du: "Suche in Wiki.js nach allen osTicket-Plugin-Dokumentationen
und zeige mir die Naming-Conventions."
Claude: *Sucht in Wiki.js*
*Extrahiert relevante Informationen*
*Wendet diese auf deinen aktuellen Code an*
3. Content-Reorganisation
Du: "Alle Seiten unter /legacy/ sollten nach /archive/ verschoben werden."
Claude: *Listet alle /legacy/ Seiten auf*
*Verschiebt sie systematisch nach /archive/*
*Aktualisiert interne Links*
¶ Voraussetzungen
- Node.js 18+ installiert
- Wiki.js Instanz mit aktivierter GraphQL API
- Wiki.js API Token mit passenden Berechtigungen
¶ Installation
¶ Schritt 1: Repository klonen
# MCP-Server Directory erstellen
mkdir -p ~/.claude/mcp-servers/wikijs
# Repository klonen
git clone https://github.com/markus-michalski/wikijs-mcp-server.git ~/.claude/mcp-servers/wikijs
¶ Schritt 2: Dependencies installieren
cd ~/.claude/mcp-servers/wikijs
npm install
npm run build
¶ Schritt 3: Umgebungsvariablen konfigurieren
cd ~/.claude/mcp-servers/wikijs
cp .env.example .env
Bearbeite ~/.claude/mcp-servers/wikijs/.env:
WIKIJS_API_URL=https://deine-wiki-instance.com/graphql
WIKIJS_API_TOKEN=dein-api-token-hier
Wichtig: Der Server lädt automatisch die .env-Datei aus ~/.claude/mcp-servers/wikijs/.env beim Start. Du musst KEINE Umgebungsvariablen in .claude.json setzen.
¶ Schritt 4: Wiki.js API Token erstellen
- Login ins Wiki.js Admin Panel
- Navigiere zu Administration → API Access
- Klicke Generate New Key
- Name:
Claude Code MCP Server - Wähle Berechtigungen:
- ✅
read:pages- Seiten lesen - ✅
write:pages- Seiten erstellen und aktualisieren - ✅
manage:pages- Seiten löschen und verschieben
- ✅
- Klicke Generate
- Kopiere den Token in
~/.claude/mcp-servers/wikijs/.env
¶ Schritt 5: MCP Server in Claude Code registrieren
Es gibt zwei Möglichkeiten, den MCP Server zu registrieren. Wir empfehlen den CLI-Befehl, da er einfacher und weniger fehleranfällig ist.
¶ Option A: Mit Claude CLI (Empfohlen)
Nutze den claude mcp add Befehl, um den Server global zu registrieren:
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
Erklärung des Befehls:
-s user- Registriert den Server global für deinen User (in allen Projekten verfügbar)wikijs- Name des MCP Servers (frei wählbar)node- Der Befehl zum Starten des Servers~/.claude/mcp-servers/wikijs/index.js- Pfad zum Server-Einstiegspunkt
Wichtig: Ohne -s user wird der Server nur für das aktuelle Verzeichnis registriert!
Du kannst die Registrierung überprüfen mit:
claude mcp list
¶ Option B: Manuelle Konfiguration
Alternativ kannst du ~/.claude.json manuell bearbeiten und zur mcpServers-Sektion hinzufügen:
{
"mcpServers": {
"wikijs": {
"type": "stdio",
"command": "node",
"args": [
"/home/DEIN_USERNAME/.claude/mcp-servers/wikijs/index.js"
],
"env": {}
}
}
}
Hinweis: Ersetze /home/DEIN_USERNAME/ mit deinem tatsächlichen Home-Verzeichnis-Pfad.
¶ Schritt 6: Claude Code neu starten
# Claude Code beenden
/exit
# Claude Code neu starten
claude
Überprüfe die Verbindung:
/mcp
Du solltest "wikijs" mit Status "✓ connected" sehen.
¶ Verfügbare Tools
¶ ✨ create_page - Seite erstellen
Erstellt eine neue Seite in Wiki.js.
Parameter:
path(erforderlich) - Seiten-Pfad (z.B. "osticket/plugin-name")title(erforderlich) - Seiten-Titelcontent(erforderlich) - Seiten-Inhalt (Markdown oder HTML)description(erforderlich) - Kurze Seitenbeschreibunglocale(optional) - Sprache (Standard: "en")editor(optional) - Editor-Typ: "markdown", "code", "ckeditor" (Standard: "markdown")isPublished(optional) - Sofort veröffentlichen (Standard: true)isPrivate(optional) - Private Seite mit eingeschränktem Zugriff (Standard: false)tags(optional) - Array von Tags (Standard: [])
Beispiel:
{
"path": "osticket/ticket-merge-plugin",
"title": "Ticket Merge Plugin - Technische Dokumentation",
"content": "# Technische Dokumentation\\n\\n...",
"description": "Detaillierte technische Dokumentation für das Ticket Merge Plugin",
"locale": "de",
"editor": "markdown",
"isPublished": true,
"isPrivate": false,
"tags": ["osticket", "plugin", "entwicklung"]
}
¶ 🔄 update_page - Seite aktualisieren
Aktualisiert eine bestehende Seite. Unterstützt reine Metadaten-Updates ohne vollständigen Content.
Parameter:
id(optional) - Seiten-ID (verwende dies ODER path)path(optional) - Seiten-Pfad (verwende dies ODER id)locale(optional) - Seiten-Sprache (Standard: "en", erforderlich bei path)content(optional) - Neuer Inhalttitle(optional) - Neuer Titeldescription(optional) - Neue BeschreibungisPublished(optional) - Veröffentlichungsstatustags(optional) - Neues Tags-Array
Auto-Preservation (v2.1.0+):
Wenn du content oder tags nicht angibst, werden die bestehenden Werte automatisch beibehalten. Dies ermöglicht reine Metadaten-Updates, ohne den gesamten Seiteninhalt abrufen und erneut senden zu müssen.
Beispiele:
// Content und Tags aktualisieren
{
"id": 7,
"content": "# Aktualisierter Inhalt\\n\\nNeue Informationen...",
"tags": ["osticket", "plugin", "updated"]
}
// Nur Metadaten aktualisieren (Content wird automatisch beibehalten)
{
"id": 7,
"isPublished": true
}
// Per Pfad aktualisieren
{
"path": "osticket/plugin-name",
"locale": "de",
"title": "Neuer Titel",
"isPublished": true
}
Wichtig: Nach jedem API-Update immer
isPublished: truesetzen, wenn die Seite veröffentlicht bleiben soll. Die Wiki.js API kann den Veröffentlichungsstatus bei Updates zurücksetzen.
¶ 📖 get_page - Seite abrufen
Ruft eine Seite per ID oder Pfad ab.
Parameter:
id(optional) - Seiten-IDpath(optional) - Seiten-Pfad (erforderlich wenn keine ID)locale(optional) - Sprache (erforderlich bei Pfad-Nutzung)
Beispiele:
// Per ID
{ "id": 5 }
// Per Pfad
{ "path": "osticket/plugin-name", "locale": "de" }
⚠️ Wichtiger Hinweis zu Tags:
Das get_page Tool gibt keine Tags zurück. Dies ist eine Limitation der Wiki.js GraphQL API - das tags Feld wird nur bei pages.list() unterstützt, nicht bei pages.single() oder pages.singleByPath().
Workaround: Wenn du Tags einer bestimmten Seite brauchst, nutze stattdessen list_pages und filtere die Ergebnisse nach ID oder Pfad.
¶ 📋 list_pages - Seiten auflisten
Listet alle Seiten mit optionaler Filterung auf. Dieses Tool gibt auch Tags zurück!
Parameter:
locale(optional) - Nach Sprache filternlimit(optional) - Maximale Ergebnisse (Standard: 100)
Beispiel:
{
"locale": "de",
"limit": 50
}
¶ 🔍 search_pages - Seiten suchen
Sucht Seiten nach Suchbegriff.
Parameter:
query(erforderlich) - Suchbegrifflocale(optional) - Nach Sprache filtern
Beispiel:
{
"query": "osTicket Plugin",
"locale": "de"
}
¶ 🗑️ delete_page - Seite löschen
Löscht eine Seite (unwiderruflich!).
Parameter:
id(erforderlich) - Seiten-ID zum Löschen
Beispiel:
{ "id": 123 }
¶ 📦 move_page - Seite verschieben
Verschiebt eine Seite zu einem neuen Pfad.
Parameter:
id(erforderlich) - Seiten-IDdestinationPath(erforderlich) - Neuer PfaddestinationLocale(optional) - Ziel-Sprache (Standard: "en")
Beispiel:
{
"id": 5,
"destinationPath": "projekte/osticket/ticket-merge",
"destinationLocale": "de"
}
¶ Verwendungsbeispiele
¶ Beispiel 1: Plugin-Dokumentation nach Entwicklung erstellen
Nach Fertigstellung eines Plugins automatisch umfassende Wiki.js-Dokumentation erstellen:
Du in Claude Code:
"Ich habe gerade das Ticket-Merge-Plugin fertig entwickelt.
Erstelle eine ausführliche technische Wiki-Seite"
Claude:
1. Analysiert den Code in src/
2. Liest die README.md
3. Extrahiert API-Endpoints, Klassen, Methods
4. Generiert strukturierte Markdown-Dokumentation
5. Erstellt automatisch Wiki-Seite mit:
- Architektur-Übersicht
- Komponenten-Struktur
- API-Dokumentation
- Code-Beispiele
- Troubleshooting-Tipps
¶ Beispiel 2: Seite mit neuen Informationen aktualisieren
Du: "Füge der Seite über das Ticket-Merge-Plugin einen
Abschnitt über Performance-Optimierung hinzu"
Claude:
1. Ruft aktuelle Seite ab via get_page
2. Analysiert bestehenden Content
3. Generiert neuen Abschnitt
4. Aktualisiert Seite via update_page
¶ Beispiel 3: Suchen und Reorganisieren
Du: "Finde alle osTicket-Seiten und verschiebe sie unter projekte/osticket/"
Claude:
1. Sucht via search_pages nach "osTicket"
2. Listet gefundene Seiten auf
3. Verschiebt jede Seite via move_page zum neuen Pfad
4. Gibt Zusammenfassung aus
¶ Workflow: Plugin-Entwicklung → Wiki-Dokumentation
Typischer Workflow:
- Plugin entwickeln - Code schreiben, kurze README.md erstellen (user-fokussiert)
- Claude Code erstellt detaillierte Wiki-Seite - Automatisch via MCP
- Wiki-Seite enthält:
- Technische Architektur-Details
- Code-Flow-Diagramme
- API-Dokumentation
- Fortgeschrittenes Troubleshooting
- Entwickler-Notizen
- README.md bleibt kompakt - 100-200 Zeilen, user-first
- Wiki.js hat tiefe technische Docs - 500+ Zeilen, developer-first
Vorteile:
- ✅ Keine doppelte Arbeit
- ✅ Trennung der Belange (User-Docs vs. Tech-Docs)
- ✅ Automatisierte Dokumentations-Generierung
- ✅ Konsistente Struktur
¶ Troubleshooting
¶ "Missing required environment variables"
Problem: .env-Datei nicht gefunden oder unvollständig
Lösung:
- Stelle sicher, dass
.envunter~/.claude/mcp-servers/wikijs/.envexistiert - Überprüfe, dass
WIKIJS_API_URLundWIKIJS_API_TOKENgesetzt sind - Checke
.env.examplefür das korrekte Format
¶ "GraphQL Error: Forbidden"
Problem: API-Token hat nicht die erforderlichen Berechtigungen
Lösung:
- Gehe zu Wiki.js Admin Panel → API Access
- Bearbeite deinen API-Key
- Stelle sicher, dass diese Berechtigungen aktiviert sind:
- ✅
read:pages - ✅
write:pages - ✅
manage:pages
- ✅
- Generiere Token neu falls nötig
¶ "HTTP error! status: 404"
Problem: Falsche API-URL
Lösung:
- Überprüfe
WIKIJS_API_URLin~/.claude/mcp-servers/wikijs/.env - Muss mit
/graphqlenden - Beispiel:
https://deine-wiki.com/graphql
¶ Server erscheint nicht in Claude Code / Status "failed"
Problem: MCP-Konfiguration nicht geladen oder Server-Start fehlgeschlagen
Lösung:
- Checke
~/.claude.jsonSyntax (muss valides JSON sein) - Überprüfe Dateipfad zu
index.jsist korrekt - Stelle sicher, dass
.env-Datei existiert - Führe
/mcpin Claude Code aus um Server-Status zu sehen - Starte Claude Code komplett neu (
/exitdann neu starten)
¶ MCP Server nur in einem Verzeichnis verfügbar
Problem: Server funktioniert in einem Projekt, aber nicht in anderen
Ursache: Server wurde ohne -s user Flag registriert (nur lokale Registrierung)
Lösung:
# Global für alle Projekte registrieren
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/index.js
# Registrierung überprüfen
claude mcp list
¶ Technische Details
¶ Projekt-Struktur
wikijs-mcp-server/
├── src/
│ ├── index.ts # MCP-Server Entry Point
│ ├── constants.ts # Konfigurations-Konstanten
│ ├── types.ts # TypeScript Type-Definitionen
│ ├── schemas/
│ │ └── index.ts # Zod Validierungs-Schemas
│ ├── services/
│ │ ├── client.ts # Wiki.js GraphQL Client
│ │ └── error-handler.ts # Zentrales Error-Handling
│ └── tools/
│ ├── index.ts # Tool-Exports
│ ├── create-page.ts
│ ├── update-page.ts
│ ├── get-page.ts
│ ├── list-pages.ts
│ ├── search-pages.ts
│ ├── delete-page.ts
│ └── move-page.ts
├── tests/
│ └── update-page.test.ts # Unit-Tests
├── dist/ # Kompiliertes JavaScript
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
¶ Verwendete Technologien
- TypeScript - Typsichere Entwicklung
- @modelcontextprotocol/sdk - MCP Server SDK
- Zod - Runtime-Validierung
- Vitest - Unit-Testing
- dotenv - Environment Variable Loading
¶ Best Practices
¶ 1. Konsistente Pfad-Struktur
Verwende eine klare Hierarchie für Wiki-Pfade:
projekte/osticket/plugins/ticket-merge
projekte/oxid/module/payment-gateway
tutorials/symfony/testing
¶ 2. Aussagekräftige Tags
Nutze Tags für bessere Suchbarkeit:
tags: ["osticket", "plugin", "api", "entwicklung"]
¶ 3. Descriptions schreiben
Gute Descriptions helfen bei der Suche:
description: "Technische Dokumentation für osTicket Ticket-Merge-Plugin mit API-Referenz"
¶ 4. Bei Updates immer isPublished setzen
Wenn du Seiten über die API aktualisierst, setze immer explizit isPublished: true, wenn die Seite veröffentlicht bleiben soll:
{
"id": 42,
"title": "Aktualisierter Titel",
"isPublished": true // Immer angeben!
}
¶ Lizenz
MIT License - Siehe LICENSE-Datei für Details
¶ Autor
Markus Michalski
- Website: markus-michalski.net
- Wiki: faq.markus-michalski.net
- GitHub: @markus-michalski