An MCP server that bridges AI agents to a Wiki.js instance, enabling them to search, read, create, update, and delete wiki pages via the Wiki.js GraphQL API.
This article was originally posted on Wiki.js official Discussions to help those who need it, but it was deleted for unknown reasons, so it is rewritten here.
requarks-wiki-mcp is an MCP server designed to let MCP clients like Claude Code or Claude Desktop use Wiki.js as a knowledge base.
| Item | Value |
|---|---|
| Package | @yowu-dev/requarks-wiki-mcp |
| Version | v0.3.1 |
| License | MIT |
| Node.js | 20+ |
| Transport | stdio (stdin/stdout) |
| GitHub | uyu423/requarks-wiki-mcp |
| npm | @yowu-dev/requarks-wiki-mcp |
requarks-wiki-mcp/
├── src/
│ ├── index.ts # Bootstrap: config → ctx → register tools → connect
│ ├── types.ts # Shared types: WikiConfig, ToolContext, ToolModule
│ ├── config.ts # Env parsing: loadConfig() → WikiConfig
│ ├── errors.ts # Error taxonomy (WikiError hierarchy) + LLM formatting
│ ├── graphql.ts # GraphQL client factory (timeout + retry)
│ ├── safety.ts # Mutation guards + path normalization + audit logging
│ ├── resources/ # MCP resources (markdown guide, mermaid guide, permissions guide)
│ └── tools/ # One file per tool (29 total)
│ ├── registry.ts # Exports allTools[] (single import for bootstrap)
│ ├── searchPages.ts # wikijs_search_pages
│ ├── createPage.ts # wikijs_create_page (mutation)
│ └── ... # Remaining 27 tools
├── test/ # node:test based tests
├── dist/ # Build output
└── package.json # ESM, Node >=20
Administration → API in Wiki.js adminTo use with Claude Code, add it to the mcpServers field in ~/.claude.json.
Claude Code loads MCP servers from
~/.claude.json.~/.claude/.mcp.jsonandsettings.json'smcpServersare ignored.
{
"mcpServers": {
"wikijs": {
"command": "npx",
"args": ["-y", "@yowu-dev/requarks-wiki-mcp@latest"],
"env": {
"WIKI_BASE_URL": "https://wiki.your-domain.dev",
"WIKI_API_TOKEN": "your_wikijs_api_key_jwt",
"WIKI_GRAPHQL_PATH": "/graphql",
"WIKI_DEFAULT_LOCALE": "en",
"WIKI_DEFAULT_EDITOR": "markdown",
"WIKI_MUTATIONS_ENABLED": "true",
"WIKI_MUTATION_CONFIRM_TOKEN": "",
"WIKI_MUTATION_DRY_RUN": "false",
"WIKI_ALLOWED_MUTATION_PATH_PREFIXES": "",
"WIKI_HTTP_TIMEOUT_MS": "15000",
"WIKI_HTTP_MAX_RETRIES": "2"
}
}
}
}
You can also run it directly from a local build without npm publish.
git clone https://github.com/uyu423/requarks-wiki-mcp.git
cd requarks-wiki-mcp
npm install && npm run build
{
"mcpServers": {
"wikijs": {
"command": "node",
"args": ["/absolute/path/to/requarks-wiki-mcp/dist/index.js"],
"env": {
"WIKI_BASE_URL": "https://wiki.your-domain.dev",
"WIKI_API_TOKEN": "your_wikijs_api_key_jwt",
"WIKI_MUTATIONS_ENABLED": "true"
}
}
}
}
| Variable | Required | Default | Description |
|---|---|---|---|
WIKI_BASE_URL |
Yes | - | Wiki.js base URL |
WIKI_API_TOKEN |
Yes | - | Wiki.js API key JWT |
WIKI_GRAPHQL_PATH |
No | /graphql |
GraphQL endpoint path |
WIKI_DEFAULT_LOCALE |
No | en |
Default locale |
WIKI_DEFAULT_EDITOR |
No | markdown |
Default editor |
WIKI_MUTATIONS_ENABLED |
No | false |
Enable write tools |
WIKI_MUTATION_CONFIRM_TOKEN |
No | (empty) | Extra safety gate token |
WIKI_MUTATION_DRY_RUN |
No | true |
Dry-run mode (preview only) |
WIKI_ALLOWED_MUTATION_PATH_PREFIXES |
No | (empty) | Allowed write path prefixes (comma-separated) |
WIKI_HTTP_TIMEOUT_MS |
No | 15000 |
HTTP timeout (ms) |
WIKI_HTTP_MAX_RETRIES |
No | 2 |
Max retries for read failures |
| Tool | Description |
|---|---|
wikijs_search_pages |
Full-text search across wiki pages |
wikijs_list_pages |
List pages with locale filter and sorting |
wikijs_get_page_by_path |
Get page content by path + locale |
wikijs_get_page_by_id |
Get page content by numeric ID |
wikijs_get_page_tree |
Browse site hierarchy (folders/pages/all) |
wikijs_get_page_history |
View page edit history |
wikijs_get_page_version |
Get a specific version's full content |
wikijs_get_page_links |
Get page link relationships (knowledge graph) |
| Tool | Description |
|---|---|
wikijs_list_tags |
List all tags |
wikijs_search_tags |
Search tags matching a query |
| Tool | Description |
|---|---|
wikijs_list_comments |
List all comments for a page |
wikijs_get_comment |
Get a single comment by ID |
| Tool | Description |
|---|---|
wikijs_get_system_info |
Wiki.js version, DB type, usage stats |
wikijs_get_navigation |
Navigation tree structure |
wikijs_get_site_config |
Site configuration (non-sensitive fields) |
wikijs_list_assets |
List assets |
wikijs_list_asset_folders |
List asset folders |
wikijs_get_current_user |
Current authenticated user profile |
wikijs_search_users |
Search users |
Write tools are only enabled when
WIKI_MUTATIONS_ENABLED=true.
| Tool | Description |
|---|---|
wikijs_create_page |
Create a new page with content, tags, metadata |
wikijs_update_page |
Update an existing page |
wikijs_delete_page |
Delete a page |
wikijs_move_page |
Move/rename a page |
wikijs_restore_page |
Restore to a previous version |
| Tool | Description |
|---|---|
wikijs_create_comment |
Create a comment on a page |
wikijs_update_comment |
Update a comment |
wikijs_delete_comment |
Delete a comment |
| Tool | Description |
|---|---|
wikijs_update_tag |
Update a tag's slug/title |
wikijs_delete_tag |
Delete a tag from all pages |
This MCP server provides 4-layer safety gates to prevent unintended writes.
WIKI_MUTATIONS_ENABLED defaults to false, blocking all write tools unless explicitly enabled.
When WIKI_MUTATION_CONFIRM_TOKEN is set, all write calls require a matching confirm value. Uses timing-safe comparison to prevent timing attacks.
WIKI_ALLOWED_MUTATION_PATH_PREFIXES restricts which paths allow writes. Example: setting dev,tips only allows writes under dev/ and tips/.
When WIKI_MUTATION_DRY_RUN=true (default), writes return a preview instead of executing.
All mutation attempts (including dry-run) are logged as structured JSON to stderr. Sensitive information (API tokens, etc.) is automatically [REDACTED].
Provides typed error taxonomy with fix instructions so LLMs can self-diagnose issues.
| Error Class | Code | Description |
|---|---|---|
WikiAuthError |
401 | API token authentication failed |
WikiForbiddenError |
403 | Insufficient permissions (6008~6013) |
WikiNotFoundError |
404 | Page/comment not found |
WikiValidationError |
422 | Input validation failed |
WikiTransientError |
5xx | Temporary server error |
WikiRateLimitedError |
429 | Rate limit exceeded |
WikiMutationDisabledError |
- | Mutations disabled |
WikiInvalidTokenError |
- | Confirm token mismatch |
WikiPathNotAllowedError |
- | Path not in allowed prefixes |
read:pages, read:sourceread:commentsread:pages, read:source, write:pagesmanage:pages or delete:pages (for delete/move)read:comments, write:comments, manage:commentsmanage:system (for tag management)This server provides 3 built-in resources. LLMs can read these resources to self-resolve Wiki.js markdown syntax, diagram authoring, or permission issues.
| Resource URI | Description |
|---|---|
wikijs://markdown-guide |
Wiki.js markdown syntax guide (CommonMark/GFM + extensions) |
wikijs://mermaid-guide |
Mermaid 8.8.2 diagram syntax guide for Wiki.js (9 supported diagram types, unsupported feature warnings, version restrictions) |
wikijs://api-permissions-guide |
API permission model, error codes, self-diagnosis guide |
To use this MCP server more effectively, it is recommended to create your own custom Claude Code Skill tailored to your environment.
By defining wiki structure, path rules, content style guides, and related document auto-linking in a system prompt through a Skill, the AI agent can manage your wiki much more systematically.
A Skill sample is available at this Gist.
~/.claude/skills/wiki-knowledge-manager/
├── skill.md # Skill definition (system prompt)
└── ...
Keep the API token server-side only. Never expose it to clients.
WIKI_MUTATIONS_ENABLED=falseWIKI_MUTATION_DRY_RUN=true before enabling writesWIKI_MUTATION_CONFIRM_TOKEN in productionWIKI_ALLOWED_MUTATION_PATH_PREFIXESwikijs_get_system_info auto-excludes dbHost, configFile, etc.scriptJs/scriptCss fields are limited to 10,000 charspages.tree mode must be passed as GraphQL enum (FOLDERS, PAGES, ALL)pages.history paginates with offsetPage/offsetSize (not offset/limit)locale field returns null — do not request itupdate with undefined tags crashes Wiki.js with .map() error (always pass [])update with null description is rejected (use undefined or a string value)