¶ Wiki.js MCP Server
¶ Table of Contents
- Overview
- Features
- Use Cases
- Requirements
- Installation
- Configuration
- Available Tools
- Usage Examples
- Troubleshooting
- Technical Details
- FAQ
- License
¶ Overview
The Wiki.js MCP Server enables Claude to interact directly with your Wiki.js instance via the Model Context Protocol (MCP). Create, update, search, and manage wiki pages directly from Claude Code - without manual copy-paste or browser switching.
This MCP server enables Claude to interact directly with Wiki.js - without manual copy-paste or browser switching. Documentation is automatically generated while you develop.
¶ Architecture
¶ 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 pages - Retrieve pages by ID or path
- List pages - List all pages with pagination and optional locale filtering
- Search pages - Full-text search across all wiki content
- Delete pages - Remove pages from the wiki
- Move pages - Reorganize content by changing paths
- MCP Protocol Compliant - Fully conforming to MCP 1.0 specification
- Zod Validation - Runtime validation of all input parameters
¶ Use Cases
1. Automatic Documentation After Plugin Development
You develop a plugin in Claude Code and say: "Create a comprehensive wiki page for this." Claude analyzes the code, architecture, and API and automatically creates a structured wiki page.
2. Knowledge Management During Development
Search Wiki.js for existing documentation 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.
5. Batch Updates
Efficiently update tags, descriptions, or publication status of multiple pages.
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| Node.js | 18+ | Runtime environment |
| Wiki.js | 2.x or 3.x | With GraphQL API enabled |
| Wiki.js API Token | - | Permissions: read:pages, write:pages, manage:pages |
| Claude Desktop or CLI | Current | As MCP client |
| npm | 8+ | Package manager |
npm install -g @markus-michalski/wikijs-mcp-server
Then register in Claude Code:
claude mcp add -s user wikijs -- wikijs-mcp-server
# Create MCP server directory
mkdir -p ~/.claude/mcp-servers/wikijs
# Clone repository
git clone https://github.com/markus-michalski/wikijs-mcp-server.git ~/.claude/mcp-servers/wikijs
# Install dependencies and build
cd ~/.claude/mcp-servers/wikijs
npm install
npm run build
Then register in Claude Code:
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
¶ 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 ~/.claude/mcp-servers/wikijs/.env at startup. Falls back to .env in the current directory.
# Create .env file
cp .env.example ~/.claude/mcp-servers/wikijs/.env
Edit ~/.claude/mcp-servers/wikijs/.env:
WIKIJS_API_URL=https://your-wiki-instance.com/graphql
WIKIJS_API_TOKEN=your-api-token-here
You do NOT need to set environment variables in the Claude MCP configuration. The server loads them automatically from the
.envfile.
¶ Create Wiki.js API Token
- Login to Wiki.js Admin Panel
- Navigate to Administration - API Access
- Click Generate New Key
- Name:
Claude Code MCP Server - 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.
¶ Claude Desktop Integration
{
"mcpServers": {
"wikijs": {
"command": "node",
"args": ["/home/YOUR_USERNAME/.claude/mcp-servers/wikijs/dist/index.js"],
"env": {}
}
}
}
¶ Claude CLI Integration
# Register globally (recommended)
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
# Verify registration
claude mcp list
Without
-s user, the server is only registered for the current directory and won't be available in other projects.
¶ Verify Connection
After restarting Claude Code:
/mcp
You should see wikijs with status "connected".
¶ 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": 8, "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.
The
get_pagetool does not return tags. This is a limitation of the Wiki.js GraphQL API. Uselist_pagesinstead and filter by ID or path.
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. This tool also returns tags.
| 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": 120,
"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: "I just finished developing the Ticket Merge Plugin.
Create a comprehensive technical wiki page."
Claude:
1. Analyzes the code in src/
2. Reads the README.md
3. Extracts API endpoints, classes, methods
4. Generates structured Markdown documentation
5. Creates wiki page 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
¶ Server Won't Start
Symptom: Missing required environment variables: WIKIJS_API_URL, WIKIJS_API_TOKEN
Check:
- Does
~/.claude/mcp-servers/wikijs/.envexist? - Are
WIKIJS_API_URLandWIKIJS_API_TOKENset?
Solution:
cp .env.example ~/.claude/mcp-servers/wikijs/.env
# Edit file with correct values
¶ Authentication Failed
Symptom: GraphQL Error: Forbidden
Check: Does the API token have the required permissions?
Solution:
- Open Wiki.js Admin Panel - API Access
- Edit your API key
- Enable permissions:
read:pages,write:pages,manage:pages - Regenerate token if needed
¶ Wrong API Endpoint
Symptom: HTTP error! status: 404
Check: Is WIKIJS_API_URL correct?
Solution:
The URL must end with /graphql, e.g., https://your-wiki.com/graphql
¶ Server Not Appearing in Claude Code
Symptom: Server not listed in /mcp or status "failed"
Check:
- Verify
~/.claude.jsonsyntax (must be valid JSON) - Verify file path to
dist/index.js - Verify
.envfile exists
Solution:
# Re-register
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
# Completely restart Claude Code
/exit
claude
¶ Server Only Available in One Directory
Symptom: Server works in one project but not in others
Cause: Server was registered without -s user flag
Solution:
claude mcp add -s user wikijs node ~/.claude/mcp-servers/wikijs/dist/index.js
¶ Timeout on Large Pages
Symptom: Request times out
Check: Is the Wiki.js instance reachable and performant?
Solution: The API timeout is 30 seconds. For very large pages (>100k chars), content may be automatically truncated.
¶ Technical Details
¶ Project Structure
wikijs-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point + tool registration
│ ├── constants.ts # Configuration constants
│ ├── types.ts # TypeScript type definitions
│ ├── schemas/
│ │ └── index.ts # Zod validation schemas for all tools
│ ├── services/
│ │ ├── client.ts # WikiJsClient - GraphQL client
│ │ └── error-handler.ts # Centralized error handling
│ └── tools/
│ ├── index.ts # Tool exports
│ ├── create-page.ts # wikijs_create_page
│ ├── update-page.ts # wikijs_update_page (with 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/ # Compiled JavaScript (tsc)
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── .env.example
¶ Constants
| Constant | Value | Description |
|---|---|---|
CHARACTER_LIMIT |
100,000 | Maximum content length before truncation |
DEFAULT_PAGE_LIMIT |
50 | Default pagination limit |
MAX_PAGE_LIMIT |
200 | Maximum pagination limit |
API_TIMEOUT |
30,000 ms | GraphQL request timeout |
¶ Architecture Details
Transport: stdio (standard MCP transport)
Protocol: MCP 1.0
API: Wiki.js GraphQL API with Bearer Token Authentication
Validation: Zod runtime schemas with descriptive error messages
¶ Technologies Used
| Technology | Purpose |
|---|---|
| TypeScript (strict mode) | Type-safe development |
| @modelcontextprotocol/sdk v1.24+ | MCP Server SDK with McpServer.tool() API |
| Zod | Runtime validation of all inputs |
| Vitest | Unit testing |
| dotenv | Environment variable loading |
¶ Security Features
- Bearer Token Authentication - All API requests authenticated
- Zod Input Validation - All parameters validated before processing
- Character Limit - Prevents LLM context overflow on large pages
- Graceful Shutdown - Clean shutdown on SIGINT, SIGTERM, and uncaughtException (EPIPE is ignored)
- Tool Annotations -
destructiveHint: trueon delete,readOnlyHint: trueon read tools
¶ 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.
Which MCP clients are supported?
Any MCP-compatible client. Tested with Claude Desktop and Claude CLI (Claude Code).
Which Node.js version is required?
Node.js 18 or higher. The server uses ES Modules ("type": "module" in package.json).
Can I use the server without npm global install?
Yes, clone the repository and register the server with the path to dist/index.js.
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