¶ Wiki.js Plugin
This documentation always describes the latest published version. For older versions, see the CHANGELOG.
Using Wiki.js with another MCP client (not Claude Code)? The standalone wikijs-mcp-server (Node.js) is the right choice for that.
¶ Table of Contents
- Overview
- Features
- Use Cases
- Requirements
- Installation
- Configuration
- docs-wiki Skill
- Available Tools
- Usage Examples
- Troubleshooting
- Technical Details
- FAQ
- License
¶ Overview
wikijs-plugin is an installable Claude Code plugin for Wiki.js: a Python MCP server (create, update, search, and manage pages) combined with the docs-wiki skill, which orchestrates documentation agents and publishes directly to Wiki.js.
One plugin, two building blocks: the MCP server provides the
wikijs_*tools, thedocs-wikiskill uses them to automatically turn code into structured DE+EN documentation - without manual copy-paste or browser switching.
The plugin is installed via the Claude Code marketplace mechanism - no more manual cloning, building, or registering.
¶ Features
- Create pages - New wiki pages with Markdown or HTML content
- Update pages - Edit existing pages (content, title, description, tags)
- Auto-content preservation - On metadata-only updates, content is automatically retained
- Get, list (with pagination), full-text search, delete, and move pages
docs-wikiskill - Orchestrates documentation agents (docs-architect, mermaid-expert, tutorial-engineer, api-documenter, reference-builder) for new docs, updates, or quality upgrades- Marketplace installation - No manual setup, dedicated venv at
~/.wikijs-plugin/venv/ - MCP Protocol Compliant - Fully conforming to the current MCP specification
¶ Use Cases
1. Automatic Documentation After Plugin Development
You develop a plugin in Claude Code and invoke /wikijs-plugin:docs-wiki. Claude analyzes the code, architecture, and API and automatically creates a structured, bilingual wiki page.
2. Knowledge Management During Development
Search Wiki.js for existing documentation via wikijs_search_pages and apply found conventions to your current code.
3. Content Reorganization
Systematically move pages between paths, e.g., all pages under /legacy/ to /archive/.
4. Multilingual Documentation
Create wiki pages simultaneously in DE and EN with consistent structure - the docs-wiki skill enforces this.
5. Quality Upgrade of Existing Pages
Upgrade thin existing wiki pages with Mermaid diagrams, callout boxes, tabs, and troubleshooting sections.
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.11+ | For the /wikijs-plugin:setup skill; on Windows the py launcher resolves this reliably even when python/python3 point at the Microsoft Store alias stub |
| Wiki.js | 2.x or 3.x | With GraphQL API enabled |
| Wiki.js API Token | - | Permissions: read:pages, write:pages, manage:pages |
| Claude Code | Current | Installed via the plugin marketplace mechanism |
¶ Installation
# Register the marketplace
claude plugin marketplace add markus-michalski/wikijs-plugin
# Install the plugin
claude plugin install wikijs-plugin@wikijs-plugin
Then restart Claude Code and run the setup skill:
/wikijs-plugin:setup
The skill creates a dedicated venv at ~/.wikijs-plugin/venv/, installs Python dependencies, and copies the .env template to ~/.wikijs-plugin/.env.
Already using wikijs-mcp-server (Node.js) for Claude Code? Just copy the existing values from your old
.envinto the new~/.wikijs-plugin/.env- same keys (WIKIJS_API_URL,WIKIJS_API_TOKEN), no new API token needed. Then remove the old manual MCP registration so the tools don't appear twice.
¶ Configuration
¶ Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
WIKIJS_API_URL |
Yes | - | GraphQL endpoint of the Wiki.js instance (e.g., https://wiki.example.com/graphql) |
WIKIJS_API_TOKEN |
Yes | - | API token with page management permissions |
The server automatically loads the .env file from ~/.wikijs-plugin/.env on the first tool call - this path lives outside the plugin directory and survives plugin updates.
WIKIJS_API_URL=https://your-wiki-instance.com/graphql
WIKIJS_API_TOKEN=your-api-token-here
Changes to
~/.wikijs-plugin/.envonly take effect after restarting Claude Code - the MCP server keeps the credentials it loaded for the lifetime of the process.
¶ Create Wiki.js API Token
- Login to Wiki.js Admin Panel
- Navigate to Administration - API Access
- Click Generate New Key
- Name:
wikijs-plugin - Select permissions:
read:pages- Read pageswrite:pages- Create and update pagesmanage:pages- Delete and move pages
- Click Generate and copy the token to the
.envfile
Without
manage:pages,delete_pageandmove_pagewill not work. If you only need read/write access,read:pagesandwrite:pagesare sufficient.
¶ Verify Connection
After restarting Claude Code:
/mcp
You should see wikijs-mcp with status "connected".
¶ docs-wiki Skill
/wikijs-plugin:docs-wiki orchestrates documentation agents for structured, bilingual Wiki.js pages:
- Choose project type - osTicket, Shopware6, OXID, MCP, Bash/Shell, Claude Agent
- Name the project - free text, e.g. the repo name
- Choose mode - new docs, update, or quality upgrade
- Orchestrate agents - docs-architect (always), mermaid-expert (always), tutorial-engineer, api-documenter, reference-builder (as needed)
- Publish - DE + EN via
wikijs_create_page/wikijs_update_page,isPublished: true
If the MCP server is unreachable, that only blocks the publish step - the skill still generates complete DE+EN content for manual copy-paste.
¶ Available Tools
¶ Tool Overview
| Tool | Description | Parameters |
|---|---|---|
wikijs_create_page |
Create a new wiki page | path, title, content, description, locale, editor, isPublished, isPrivate, tags |
wikijs_update_page |
Update an existing page | id/path, locale, content, title, description, isPublished, tags |
wikijs_get_page |
Retrieve a page by ID or path | id/path, locale |
wikijs_list_pages |
List pages with pagination | locale, limit, offset |
wikijs_search_pages |
Full-text search | query, locale |
wikijs_delete_page |
Permanently delete a page | id/path, locale |
wikijs_move_page |
Move a page to a new path | id/path, locale, destinationPath, destinationLocale |
¶ wikijs_create_page - Create Page
Creates a new page in Wiki.js.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string | Yes | - | Page path without leading slash (e.g., osticket/plugin-name) |
title |
string | Yes | - | Page title (max 200 chars) |
content |
string | Yes | - | Page content (Markdown or HTML) |
description |
string | Yes | - | Short page description (max 500 chars) |
locale |
string | No | en |
Language (2-5 chars) |
editor |
string | No | markdown |
Editor type: markdown, code, ckeditor |
isPublished |
boolean | No | true |
Publish immediately |
isPrivate |
boolean | No | false |
Private page with restricted access |
tags |
string[] | No | [] |
Tags for categorization |
Example:
{
"path": "osticket/ticket-merge-plugin",
"title": "Ticket Merge Plugin",
"content": "# Technical Documentation\n\n...",
"description": "Technical documentation for the Ticket Merge Plugin",
"locale": "en",
"isPublished": true,
"tags": ["osticket", "plugin"]
}
¶ wikijs_update_page - Update Page
Updates an existing page. Identification by ID or path+locale.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id |
number | No* | - | Page ID |
path |
string | No* | - | Page path |
locale |
string | No | en |
Language (required when using path) |
content |
string | No | - | New content |
title |
string | No | - | New title (max 200 chars) |
description |
string | No | - | New description (max 500 chars) |
isPublished |
boolean | No | - | Publication status |
tags |
string[] | No | - | New tags array |
*Either id or path must be provided.
Auto-Content Preservation: If
contentortagsare not provided, existing values are automatically fetched from the server and preserved. This allows metadata-only updates without content loss.
Examples:
// Metadata-only update (content is preserved)
{ "id": 202, "isPublished": true }
// Update content by path
{
"path": "osticket/plugin-name",
"locale": "en",
"content": "# New Content\n\n...",
"isPublished": true
}
¶ wikijs_get_page - Get Page
Retrieves a page by ID or path.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id |
number | No* | - | Page ID |
path |
string | No* | - | Page path |
locale |
string | No | en |
Language (required when using path) |
*Either id or path must be provided.
Content over 100,000 characters is automatically truncated with the notice
[Content truncated. Original length: XXX chars].
¶ wikijs_list_pages - List Pages
Lists all pages with pagination and optional filtering.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
locale |
string | No | - | Filter by language |
limit |
number | No | 50 |
Maximum results (1-200) |
offset |
number | No | 0 |
Number of entries to skip |
Pagination Response:
{
"pagination": {
"limit": 50,
"offset": 0,
"total_count": 191,
"has_more": true,
"next_offset": 50
}
}
¶ wikijs_search_pages - Search Pages
Full-text search across all wiki content.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | Yes | - | Search query (2-200 chars) |
locale |
string | No | - | Filter by language |
¶ wikijs_delete_page - Delete Page
Permanently and irreversibly deletes a page. Identification by ID or path+locale.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id |
number | No* | - | Page ID |
path |
string | No* | - | Page path |
locale |
string | No | en |
Language (required when using path) |
*Either id or path must be provided.
This action is IRREVERSIBLE! The page and all its history will be permanently deleted.
¶ wikijs_move_page - Move Page
Moves a page to a new path. Identification by ID or path+locale.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id |
number | No* | - | Page ID |
path |
string | No* | - | Current page path |
locale |
string | No | en |
Current language |
destinationPath |
string | Yes | - | New path (1-500 chars) |
destinationLocale |
string | No | en |
Target language |
*Either id or path must be provided.
After moving, the page URL changes. Update all external links pointing to the old path.
¶ Usage Examples
¶ Automatically Create Plugin Documentation
You: "/wikijs-plugin:docs-wiki - I just finished developing the Ticket
Merge Plugin. Create a comprehensive technical wiki page."
Claude:
1. Asks for project type (osTicket), project name, mode (new docs)
2. Loads templates, analyzes code via docs-architect
3. Generates a Mermaid diagram via mermaid-expert
4. Creates the wiki page DE+EN via wikijs_create_page
¶ Update Page with New Information
You: "Add a section about performance optimization to the
Ticket Merge Plugin page."
Claude:
1. Retrieves current page via wikijs_get_page
2. Analyzes existing content
3. Generates new section
4. Updates page via wikijs_update_page
¶ Search and Reorganize
You: "Find all osTicket pages and move them under projects/osticket/"
Claude:
1. Searches via wikijs_search_pages for "osTicket"
2. Lists found pages
3. Moves each page via wikijs_move_page to new path
4. Provides summary
¶ Troubleshooting
¶ Setup Fails / MCP Not Connected
Check: Re-run /wikijs-plugin:setup - it reports venv, dependency, and import status.
Solution: If MCP: MISSING, check the exact import error, usually missing dependencies (re-run pip install -r requirements.txt in the plugin directory).
¶ Tool Calls Fail With Credentials Error
Symptom: Missing required environment variables WIKIJS_API_URL / WIKIJS_API_TOKEN
Check: Does ~/.wikijs-plugin/.env exist with both variables set?
Solution:
cp .env.example ~/.wikijs-plugin/.env
# Edit file with correct values, then restart Claude Code
¶ Wrong API Endpoint
Symptom: getaddrinfo failed or HTTP error! status: 404
Check: Is WIKIJS_API_URL correct and does it end with /graphql?
Solution: Check the URL format, e.g., https://your-wiki.com/graphql
¶ Authentication Failed
Symptom: GraphQL Error: Forbidden
Solution: Check API token permissions in the Wiki.js Admin Panel (read:pages, write:pages, manage:pages), regenerate the token if needed.
¶ Timeout on Large Pages
Symptom: Request times out
Solution: The API timeout is 30 seconds. For very large pages (>100k chars), content may be automatically truncated.
¶ Technical Details
¶ Architecture
Transport: stdio (standard MCP transport)
MCP SDK: mcp[cli] 2.0.0 (Python)
API: Wiki.js GraphQL API with Bearer Token Authentication
¶ Project Structure
wikijs-plugin/
├── .claude-plugin/ # plugin.json + marketplace.json
├── bin/ # run-server wrapper (POSIX + Windows)
├── servers/wikijs-mcp-server/ # MCP server (mcp[cli] + httpx)
│ ├── server.py # Tool registration
│ └── tools/ # client.py, pages.py, validation.py, config.py
├── skills/docs-wiki/ # Documentation skill (this page)
└── skills/setup/ # Venv and .env setup
¶ Security Features
- Bearer Token Authentication - All API requests authenticated
- Input Validation - All parameters validated before processing
- Character Limit - Prevents LLM context overflow on large pages
- Tool Annotations -
destructiveHint: trueon delete,readOnlyHint: trueon read tools - Lazy Credential Loading -
.envis only loaded on the first tool call, soimport serverworks even without configured credentials
¶ FAQ
What is MCP?
The Model Context Protocol (MCP) is an open protocol by Anthropic that enables AI assistants like Claude to interact with external tools and services. An MCP server provides tools (functions) that Claude can call during a conversation.
Why Python instead of Node.js?
The original wikijs-mcp-server was TypeScript/Node.js. The plugin uses Python (mcp[cli] + httpx), matching the other MM plugins (mm-dev-toolkit, project-hub, storyforge) - one consistent setup pattern instead of a Node.js special case. Tool names and behavior stayed identical.
I use a different MCP client than Claude Code - what then?
The standalone wikijs-mcp-server (Node.js) remains available and unchanged for that.
Does content get lost on metadata-only updates?
No. On metadata-only updates (e.g., only changing isPublished), the server automatically fetches the existing content and sends it with the update. Content and tags are automatically preserved.
¶ License
MIT License - See LICENSE
¶ Support and Changelog
- GitHub Issues: Issues
- Changelog: CHANGELOG.md
- Wiki.js Documentation
- Model Context Protocol
- Claude Code