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:

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:

Tags:

Comments:

System & Navigation:

Assets:

Users:

Write Tools (10, disabled unless WIKI_MUTATIONS_ENABLED=true)

Page Mutations:

Comment Mutations:

Tag Mutations:

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

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:

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.