requarks-wiki-mcp

MCP server for a Wiki.js instance that lets agents use it like a knowledge base.

Features:

• 29 tools (19 read + 10 write) covering pages, comments, tags, assets, users, navigation, and system info.
• Search, list, and browse pages for retrieval workflows (RAG-like usage).
• Fetch page content by path or page ID, view version history and restore previous versions.
• Browse site hierarchy with page tree, page links graph, and navigation structure.
• Full comment system: list, read, create, update, and delete comments on pages.
• Asset and folder browsing for media file discovery.
• User context: current user profile and user search.
• System diagnostics: version info, site config, and navigation tree.
• Tag management: list, search, update, and delete tags.
• Optional page create/update/delete/move/restore tools with explicit safety gates.
• Built-in resources: markdown syntax guide, Mermaid diagram guide, and API permissions guide.
• Typed error taxonomy with LLM-friendly error messages.
• GraphQL client with timeout, exponential-backoff retry, and request correlation.
• Security hardening: sensitive field filtering, URL validation, input length limits.

Requirements

• Node.js 20+
• A reachable Wiki.js hostname
• Wiki.js API key (JWT) with proper permissions

Setup

cp .env.example .env
npm install

Configure .env:

WIKI_BASE_URL=https://your-wiki-hostname
WIKI_API_TOKEN=your_wikijs_api_key_jwt
WIKI_GRAPHQL_PATH=/graphql
WIKI_DEFAULT_LOCALE=en
WIKI_DEFAULT_EDITOR=markdown

# Mutating operations are disabled by default
WIKI_MUTATIONS_ENABLED=false
# Optional extra safety gate for writes. If set, write tools must pass matching confirm.
WIKI_MUTATION_CONFIRM_TOKEN=
WIKI_MUTATION_DRY_RUN=true
# Comma-separated path prefixes without leading slash (empty = no prefix restriction)
WIKI_ALLOWED_MUTATION_PATH_PREFIXES=

# HTTP resilience
WIKI_HTTP_TIMEOUT_MS=15000
WIKI_HTTP_MAX_RETRIES=2

Environment variable reference:

Variable	Required	Default	Description
WIKI_BASE_URL	Yes	-	Base Wiki.js URL (for example, https://wiki.example.com).
WIKI_API_TOKEN	Yes	-	Wiki.js API key JWT used in Authorization: Bearer ....
WIKI_GRAPHQL_PATH	No	/graphql	GraphQL endpoint path appended to WIKI_BASE_URL.
WIKI_DEFAULT_LOCALE	No	en	Default locale used when tool input does not provide locale.
WIKI_DEFAULT_EDITOR	No	markdown	Default editor used for page creation when not specified.
WIKI_MUTATIONS_ENABLED	No	false	Enables all write tools (page, comment, and tag mutations) when set to true.
WIKI_MUTATION_CONFIRM_TOKEN	No	`` (empty)	Optional extra safety gate. When set, write tool calls must provide matching confirm.
WIKI_MUTATION_DRY_RUN	No	true	When true, mutation tools return preview only and do not write to Wiki.js.
WIKI_ALLOWED_MUTATION_PATH_PREFIXES	No	`` (empty)	Comma-separated path prefixes (without leading slash) allowed for mutations. Empty means no prefix restriction.
WIKI_HTTP_TIMEOUT_MS	No	15000	HTTP request timeout in milliseconds (including body reads). Minimum 1.
WIKI_HTTP_MAX_RETRIES	No	2	Max retries for transient read failures (408, 502-504). Mutations are never retried. Minimum 0.

Wiki.js prerequisite (GraphQL + API key):

• This MCP uses Wiki.js GraphQL internally.
• In Wiki.js admin, go to Administration -> API and enable API access.
• Create an API key and set it as WIKI_API_TOKEN.

MCP Client Config Example (~/.mcp.json)

{
  "mcpServers": {
    "requarks-wiki": {
      "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": "CONFIRM_UPDATE",
        "WIKI_MUTATION_DRY_RUN": "false",
        "WIKI_ALLOWED_MUTATION_PATH_PREFIXES": "",
        "WIKI_HTTP_TIMEOUT_MS": "15000",
        "WIKI_HTTP_MAX_RETRIES": "2"
      }
    }
  }
}

Register MCP Via Local Path (Without npm Publish)

You can register this MCP server directly from your local project path without publishing/installing from npm.

1. Build in this repository

npm install
npm run build

2. Register local absolute path in ~/.mcp.json

{
  "mcpServers": {
    "requarks-wiki-local": {
      "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_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"
      }
    }
  }
}

Notes:

• Always use an absolute path.
• Re-run npm run build after code changes so dist/index.js stays up to date.

Run

Development:

npm run dev

Build + run:

npm run build
npm start

MCP Tools

Read Tools (19)

Pages:

Tool	Description
wikijs_search_pages	Full-text search across wiki pages.
wikijs_list_pages	List pages with optional locale filter and limit.
wikijs_get_page_by_path	Get full page content by path + locale.
wikijs_get_page_by_id	Get full page content by numeric ID.
wikijs_get_page_tree	Browse site hierarchy (folders, pages, or both).
wikijs_get_page_history	View edit history trail for a page.
wikijs_get_page_version	Get a specific version's full content.
wikijs_get_page_links	Get page link relationships (knowledge graph).

Tags:

Tool	Description
wikijs_list_tags	List all tags for content taxonomy discovery.
wikijs_search_tags	Search for tags matching a query string.

Comments:

Tool	Description
wikijs_list_comments	List all comments for a page by path and locale.
wikijs_get_comment	Get a single comment by ID.

System & Navigation:

Tool	Description
wikijs_get_system_info	Wiki.js version, database type, and usage statistics.
wikijs_get_navigation	Navigation tree structure.
wikijs_get_site_config	Site configuration (non-sensitive fields).

Assets:

Tool	Description
wikijs_list_assets	List assets with optional folder and kind filter.
wikijs_list_asset_folders	List asset folders.

Users:

Tool	Description
wikijs_get_current_user	Get the currently authenticated API user's profile.
wikijs_search_users	Search users by name or email.

Write Tools (10, disabled unless WIKI_MUTATIONS_ENABLED=true)

Page Mutations:

Tool	Description
wikijs_create_page	Create a new page with content, tags, and metadata.
wikijs_update_page	Update an existing page by ID.
wikijs_delete_page	Delete a page by ID. May need manage:pages or delete:pages.
wikijs_move_page	Move/rename a page to a new path or locale.
wikijs_restore_page	Restore a page to a previous version.

Comment Mutations:

Tool	Description
wikijs_create_comment	Create a comment on a page.
wikijs_update_comment	Update an existing comment by ID.
wikijs_delete_comment	Delete a comment by ID.

Tag Mutations:

Tool	Description
wikijs_update_tag	Update a tag's slug and title.
wikijs_delete_tag	Delete a tag from all pages.

Mutation Safety

• When WIKI_MUTATION_CONFIRM_TOKEN is set, mutation tools require a matching confirm argument.
• When WIKI_MUTATION_DRY_RUN=true, write tools return a preview and do not mutate Wiki.js.
• If WIKI_ALLOWED_MUTATION_PATH_PREFIXES is set, page and comment-create mutations are limited to those path prefixes.
• All mutation attempts write a structured audit line to stderr.

MCP Resources

Resource URI	Description
wikijs://markdown-guide	Wiki.js markdown syntax guide (CommonMark/GFM + Wiki.js-specific extensions) intended for page authoring and updates.
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	Wiki.js API permission model, error codes, and API key configuration guide for self-diagnosing permission errors.

Permission Notes (Wiki.js)

Wiki.js permission behavior can be surprising for API keys. In particular:

• Some operations may require manage:pages/delete:pages rules at page-rule level.
• Reading content may require read:source depending on schema/field-level checks.
• Comment operations require read:comments, write:comments, or manage:comments.
• System info and navigation require admin-level API key permissions.

Common error codes:

Code	Meaning
6013	PageViewForbidden — check group permissions + page rules for read:pages/read:source
6003	Page does not exist
8002	CommentPostForbidden
8003	CommentNotFound
8004	CommentViewForbidden
8005	CommentManageForbidden

For more details, read the wikijs://api-permissions-guide resource.

Suggested Minimum API Key Permissions

For read-heavy KB use:

• read:pages, read:source
• read:comments (for comment browsing)
• Page rules allowing those permissions for intended paths/locales

For write workflows:

• write:pages (create and update)
• manage:pages or delete:pages (for delete/move operations)
• write:comments, manage:comments (for comment mutations)
• manage:system (for tag management)

Security Guidance

• Keep API token server-side only.
• Start with read-only permissions.
• Keep WIKI_MUTATIONS_ENABLED=false unless updates are needed.
• Optional hardening: set a strong random WIKI_MUTATION_CONFIRM_TOKEN and pass matching confirm for write calls.
• Keep WIKI_MUTATION_DRY_RUN=true until you are ready for real writes.
• Use WIKI_ALLOWED_MUTATION_PATH_PREFIXES to constrain write scope.
• wikijs_get_system_info filters sensitive infrastructure fields (dbHost, configFile, etc.) by default.
• scriptJs/scriptCss fields in page create/update are length-limited (10,000 chars) and include browser execution warnings.