¶ Wiki.js MCP Server
¶ Inhaltsverzeichnis
- Überblick
- Features
- Anwendungsfälle
- Anforderungen
- Installation
- Konfiguration
- Verfügbare Tools
- Verwendungsbeispiele
- Fehlerbehebung
- Technische Details
- FAQ
- Lizenz
¶ Überblick
Der Wiki.js MCP Server ermöglicht Claude die direkte Interaktion mit deiner Wiki.js-Instanz über das Model Context Protocol (MCP). Erstelle, aktualisiere, suche und verwalte Wiki-Seiten direkt aus Claude Code heraus - ohne manuelles Copy-Paste oder Browser-Wechsel.
Dieser MCP Server ermöglicht Claude die direkte Interaktion mit Wiki.js - ohne manuelles Copy-Paste oder Browser-Wechsel. Dokumentation wird automatisch generiert, während du entwickelst.
¶ Architektur
¶ Features
- Seiten erstellen - Neue Wiki-Seiten mit Markdown oder HTML Content
- Seiten aktualisieren - Bestehende Seiten bearbeiten (Inhalt, Titel, Beschreibung, Tags)
- Auto-Content-Preservation - Bei reinen Metadaten-Updates wird Content automatisch beibehalten
- Seiten abrufen - Seiten per ID oder Pfad laden
- Seiten auflisten - Alle Seiten mit Pagination und 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
- MCP Protocol Compliant - Vollständig konform mit MCP 1.0 Spezifikation
- Zod Validation - Runtime-Validierung aller Eingabeparameter
¶ Anwendungsfälle
1. Automatische Dokumentation nach Plugin-Entwicklung
Du entwickelst ein Plugin in Claude Code und sagst: "Erstelle eine ausführliche Wiki-Seite dafür." Claude analysiert den Code, die Architektur und API und erstellt automatisch eine strukturierte Wiki-Seite.
2. Wissensmanagement während der Entwicklung
Suche in Wiki.js nach bestehender Dokumentation und wende die gefundenen Konventionen auf deinen aktuellen Code an.
3. Content-Reorganisation
Verschiebe systematisch Seiten zwischen Pfaden, z.B. alle Seiten unter /legacy/ nach /archive/.
4. Mehrsprachige Dokumentation
Erstelle Wiki-Seiten gleichzeitig in DE und EN mit konsistenter Struktur.
5. Batch-Updates
Aktualisiere Tags, Beschreibungen oder Veröffentlichungsstatus mehrerer Seiten effizient.
¶ Anforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| Node.js | 18+ | Runtime-Umgebung |
| Wiki.js | 2.x oder 3.x | Mit aktivierter GraphQL API |
| Wiki.js API Token | - | Berechtigungen: read:pages, write:pages, manage:pages |
| Claude Desktop oder CLI | Aktuell | Als MCP Client |
| npm | 8+ | Paketmanager |
npm install -g @markus-michalski/wikijs-mcp-server
Danach in Claude Code registrieren:
claude mcp add -s user wikijs -- wikijs-mcp-server
# 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
# Dependencies installieren und bauen
cd ~/.claude/mcp-servers/wikijs
npm install
npm run build
Danach in Claude Code registrieren:
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
¶ Konfiguration
¶ Environment Variables
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
WIKIJS_API_URL |
Ja | - | GraphQL-Endpunkt der Wiki.js-Instanz (z.B. https://wiki.example.com/graphql) |
WIKIJS_API_TOKEN |
Ja | - | API-Token mit Page-Management-Berechtigungen |
Der Server lädt automatisch die .env-Datei aus ~/.claude/mcp-servers/wikijs/.env beim Start. Fallback auf .env im aktuellen Verzeichnis.
# .env-Datei erstellen
cp .env.example ~/.claude/mcp-servers/wikijs/.env
Bearbeite ~/.claude/mcp-servers/wikijs/.env:
WIKIJS_API_URL=https://deine-wiki-instance.com/graphql
WIKIJS_API_TOKEN=dein-api-token-hier
Du musst KEINE Umgebungsvariablen in der Claude MCP-Konfiguration setzen. Der Server lädt sie automatisch aus der
.env-Datei.
¶ 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 - Berechtigungen auswählen:
read:pages- Seiten lesenwrite:pages- Seiten erstellen und aktualisierenmanage:pages- Seiten löschen und verschieben
- Klicke Generate und kopiere den Token in die
.env-Datei
Ohne
manage:pagesfunktionierendelete_pageundmove_pagenicht. Wenn du nur Lese-/Schreibzugriff brauchst, reichenread:pagesundwrite:pages.
¶ Claude Desktop Integration
{
"mcpServers": {
"wikijs": {
"command": "node",
"args": ["/home/DEIN_USERNAME/.claude/mcp-servers/wikijs/dist/index.js"],
"env": {}
}
}
}
¶ Claude CLI Integration
# Global registrieren (empfohlen)
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
# Registrierung pruefen
claude mcp list
Ohne
-s userwird der Server nur für das aktuelle Verzeichnis registriert und ist in anderen Projekten nicht verfügbar.
¶ Verbindung prüfen
Nach Neustart von Claude Code:
/mcp
Du solltest wikijs mit Status "connected" sehen.
¶ Verfügbare Tools
¶ Toolübersicht
| Tool | Beschreibung | Parameter |
|---|---|---|
wikijs_create_page |
Neue Wiki-Seite erstellen | path, title, content, description, locale, editor, isPublished, isPrivate, tags |
wikijs_update_page |
Bestehende Seite aktualisieren | id/path, locale, content, title, description, isPublished, tags |
wikijs_get_page |
Seite per ID oder Pfad abrufen | id/path, locale |
wikijs_list_pages |
Seiten mit Pagination auflisten | locale, limit, offset |
wikijs_search_pages |
Volltext-Suche | query, locale |
wikijs_delete_page |
Seite permanent löschen | id/path, locale |
wikijs_move_page |
Seite zu neuem Pfad verschieben | id/path, locale, destinationPath, destinationLocale |
¶ wikijs_create_page - Seite erstellen
Erstellt eine neue Seite in Wiki.js.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
path |
string | Ja | - | Seiten-Pfad ohne führenden Slash (z.B. osticket/plugin-name) |
title |
string | Ja | - | Seiten-Titel (max. 200 Zeichen) |
content |
string | Ja | - | Seiten-Inhalt (Markdown oder HTML) |
description |
string | Ja | - | Kurze Seitenbeschreibung (max. 500 Zeichen) |
locale |
string | Nein | en |
Sprache (2-5 Zeichen) |
editor |
string | Nein | markdown |
Editor-Typ: markdown, code, ckeditor |
isPublished |
boolean | Nein | true |
Sofort veröffentlichen |
isPrivate |
boolean | Nein | false |
Private Seite mit eingeschränktem Zugriff |
tags |
string[] | Nein | [] |
Tags für Kategorisierung |
Beispiel:
{
"path": "osticket/ticket-merge-plugin",
"title": "Ticket Merge Plugin",
"content": "# Technische Dokumentation\n\n...",
"description": "Technische Dokumentation fuer das Ticket Merge Plugin",
"locale": "de",
"isPublished": true,
"tags": ["osticket", "plugin"]
}
¶ wikijs_update_page - Seite aktualisieren
Aktualisiert eine bestehende Seite. Identifikation per ID oder Pfad+Locale.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
id |
number | Nein* | - | Seiten-ID |
path |
string | Nein* | - | Seiten-Pfad |
locale |
string | Nein | en |
Sprache (erforderlich bei Pfad-Nutzung) |
content |
string | Nein | - | Neuer Inhalt |
title |
string | Nein | - | Neuer Titel (max. 200 Zeichen) |
description |
string | Nein | - | Neue Beschreibung (max. 500 Zeichen) |
isPublished |
boolean | Nein | - | Veröffentlichungsstatus |
tags |
string[] | Nein | - | Neues Tags-Array |
*Entweder id oder path muss angegeben werden.
Auto-Content-Preservation: Wenn
contentodertagsnicht angegeben werden, werden die bestehenden Werte automatisch vom Server abgerufen und beibehalten. Dies ermöglicht reine Metadaten-Updates ohne Content-Verlust.
Beispiele:
// Nur Metadaten aktualisieren (Content bleibt erhalten)
{ "id": 7, "isPublished": true }
// Content per Pfad aktualisieren
{
"path": "osticket/plugin-name",
"locale": "de",
"content": "# Neuer Inhalt\n\n...",
"isPublished": true
}
¶ wikijs_get_page - Seite abrufen
Ruft eine Seite per ID oder Pfad ab.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
id |
number | Nein* | - | Seiten-ID |
path |
string | Nein* | - | Seiten-Pfad |
locale |
string | Nein | en |
Sprache (erforderlich bei Pfad-Nutzung) |
*Entweder id oder path muss angegeben werden.
Das
get_pageTool gibt keine Tags zurück. Dies ist eine Limitation der Wiki.js GraphQL API. Nutze stattdessenlist_pagesund filtere nach ID oder Pfad.
Inhalte über 100.000 Zeichen werden automatisch gekürzt mit dem Hinweis
[Content truncated. Original length: XXX chars].
¶ wikijs_list_pages - Seiten auflisten
Listet alle Seiten mit Pagination und optionaler Filterung auf. Dieses Tool gibt auch Tags zurück.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
locale |
string | Nein | - | Nach Sprache filtern |
limit |
number | Nein | 50 |
Maximale Ergebnisse (1-200) |
offset |
number | Nein | 0 |
Anzahl zu überspringender Einträge |
Pagination-Response:
{
"pagination": {
"limit": 50,
"offset": 0,
"total_count": 120,
"has_more": true,
"next_offset": 50
}
}
¶ wikijs_search_pages - Seiten suchen
Volltext-Suche über alle Wiki-Inhalte.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
query |
string | Ja | - | Suchbegriff (2-200 Zeichen) |
locale |
string | Nein | - | Nach Sprache filtern |
¶ wikijs_delete_page - Seite löschen
Löscht eine Seite permanent und unwiderruflich. Identifikation per ID oder Pfad+Locale.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
id |
number | Nein* | - | Seiten-ID |
path |
string | Nein* | - | Seiten-Pfad |
locale |
string | Nein | en |
Sprache (erforderlich bei Pfad-Nutzung) |
*Entweder id oder path muss angegeben werden.
Diese Aktion ist IRREVERSIBEL! Die Seite und ihre gesamte Historie werden permanent gelöscht.
¶ wikijs_move_page - Seite verschieben
Verschiebt eine Seite zu einem neuen Pfad. Identifikation per ID oder Pfad+Locale.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
id |
number | Nein* | - | Seiten-ID |
path |
string | Nein* | - | Aktueller Seiten-Pfad |
locale |
string | Nein | en |
Aktuelle Sprache |
destinationPath |
string | Ja | - | Neuer Pfad (1-500 Zeichen) |
destinationLocale |
string | Nein | en |
Ziel-Sprache |
*Entweder id oder path muss angegeben werden.
Nach dem Verschieben ändert sich die URL der Seite. Aktualisiere alle externen Links, die auf den alten Pfad verweisen.
¶ Verwendungsbeispiele
¶ Plugin-Dokumentation automatisch erstellen
Du: "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 Wiki-Seite via wikijs_create_page
¶ 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 wikijs_get_page
2. Analysiert bestehenden Content
3. Generiert neuen Abschnitt
4. Aktualisiert Seite via wikijs_update_page
¶ Suchen und Reorganisieren
Du: "Finde alle osTicket-Seiten und verschiebe sie unter projekte/osticket/"
Claude:
1. Sucht via wikijs_search_pages nach "osTicket"
2. Listet gefundene Seiten auf
3. Verschiebt jede Seite via wikijs_move_page zum neuen Pfad
4. Gibt Zusammenfassung aus
¶ Fehlerbehebung
¶ Server lässt sich nicht starten
Symptom: Missing required environment variables: WIKIJS_API_URL, WIKIJS_API_TOKEN
Prüfung:
- Existiert
~/.claude/mcp-servers/wikijs/.env? - Sind
WIKIJS_API_URLundWIKIJS_API_TOKENgesetzt?
Lösung:
cp .env.example ~/.claude/mcp-servers/wikijs/.env
# Datei mit korrekten Werten bearbeiten
¶ Authentifizierung fehlgeschlagen
Symptom: GraphQL Error: Forbidden
Prüfung: Hat der API-Token die erforderlichen Berechtigungen?
Lösung:
- Wiki.js Admin Panel - API Access öffnen
- API-Key bearbeiten
- Berechtigungen aktivieren:
read:pages,write:pages,manage:pages - Token neu generieren falls nötig
¶ Falscher API-Endpunkt
Symptom: HTTP error! status: 404
Prüfung: Ist WIKIJS_API_URL korrekt?
Lösung:
Die URL muss mit /graphql enden, z.B. https://deine-wiki.com/graphql
¶ Server erscheint nicht in Claude Code
Symptom: Server nicht in /mcp aufgelistet oder Status "failed"
Prüfung:
~/.claude.jsonSyntax prüfen (muss valides JSON sein)- Dateipfad zu
dist/index.jsprüfen .env-Datei prüfen
Lösung:
# Neu registrieren
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
# Claude Code komplett neu starten
/exit
claude
¶ Server nur in einem Verzeichnis verfügbar
Symptom: Server funktioniert in einem Projekt, aber nicht in anderen
Ursache: Server wurde ohne -s user Flag registriert
Lösung:
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
¶ Timeout bei großen Seiten
Symptom: Anfrage läuft in Timeout
Prüfung: Ist die Wiki.js-Instanz erreichbar und performant?
Lösung: Der API-Timeout beträgt 30 Sekunden. Bei sehr großen Seiten (>100k Zeichen) kann der Content automatisch gekürzt werden.
¶ Technische Details
¶ Projekt-Struktur
wikijs-mcp-server/
├── src/
│ ├── index.ts # MCP-Server Entry Point + Tool Registration
│ ├── constants.ts # Konfigurations-Konstanten
│ ├── types.ts # TypeScript Type-Definitionen
│ ├── schemas/
│ │ └── index.ts # Zod Validierungs-Schemas fuer alle Tools
│ ├── services/
│ │ ├── client.ts # WikiJsClient - GraphQL Client
│ │ └── error-handler.ts # Zentrales Error-Handling
│ └── tools/
│ ├── index.ts # Tool-Exports
│ ├── create-page.ts # wikijs_create_page
│ ├── update-page.ts # wikijs_update_page (mit Auto-Fetch)
│ ├── get-page.ts # wikijs_get_page
│ ├── list-pages.ts # wikijs_list_pages
│ ├── search-pages.ts # wikijs_search_pages
│ ├── delete-page.ts # wikijs_delete_page
│ └── move-page.ts # wikijs_move_page
├── tests/
│ └── update-page.test.ts # Vitest Unit-Tests
├── dist/ # Kompiliertes JavaScript (tsc)
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── .env.example
¶ Konstanten
| Konstante | Wert | Beschreibung |
|---|---|---|
CHARACTER_LIMIT |
100.000 | Maximale Content-Länge vor Kürzung |
DEFAULT_PAGE_LIMIT |
50 | Standard-Pagination-Limit |
MAX_PAGE_LIMIT |
200 | Maximales Pagination-Limit |
API_TIMEOUT |
30.000 ms | GraphQL Request Timeout |
¶ Architektur-Details
Transport: stdio (Standard-MCP-Transport)
Protokoll: MCP 1.0
API: Wiki.js GraphQL API mit Bearer Token Authentication
Validation: Zod Runtime-Schemas mit aussagekräftigen Fehlermeldungen
¶ Verwendete Technologien
| Technologie | Zweck |
|---|---|
| TypeScript (strict mode) | Typsichere Entwicklung |
| @modelcontextprotocol/sdk v1.24+ | MCP Server SDK mit McpServer.tool() API |
| Zod | Runtime-Validierung aller Eingaben |
| Vitest | Unit-Testing |
| dotenv | Environment Variable Loading |
¶ Sicherheits-Features
- Bearer Token Authentication - Alle API-Anfragen authentifiziert
- Zod Input Validation - Alle Parameter vor Verarbeitung validiert
- Character Limit - Verhindert LLM-Context-Overflow bei großen Seiten
- Graceful Shutdown - Sauberes Herunterfahren bei SIGINT, SIGTERM und uncaughtException (EPIPE wird ignoriert)
- Tool Annotations -
destructiveHint: truebei delete,readOnlyHint: truebei Lese-Tools
¶ FAQ
Was ist MCP?
Das Model Context Protocol (MCP) ist ein offenes Protokoll von Anthropic, das KI-Assistenten wie Claude ermöglicht, mit externen Tools und Diensten zu interagieren. Ein MCP-Server stellt Tools (Funktionen) bereit, die Claude während eines Gesprächs aufrufen kann.
Welche MCP-Clients werden unterstützt?
Jeder MCP-kompatible Client. Getestet mit Claude Desktop und Claude CLI (Claude Code).
Welche Node.js Version wird benötigt?
Node.js 18 oder höher. Der Server nutzt ES Module ("type": "module" in package.json).
Kann ich den Server ohne npm global install nutzen?
Ja, klone das Repository und registriere den Server mit dem Pfad zu dist/index.js.
Gehen bei Metadaten-Updates die Seiteninhalte verloren?
Nein. Der Server ruft bei reinen Metadaten-Updates (z.B. nur isPublished ändern) automatisch den bestehenden Content ab und sendet ihn mit dem Update mit. Content und Tags werden automatisch beibehalten.
¶ Lizenz
MIT License - Siehe LICENSE
¶ Support und Changelog
- GitHub Issues: Issues
- Changelog: CHANGELOG.md
- Wiki.js Dokumentation
- Model Context Protocol
- Claude Code