Wiki.js

Integrates with Wiki.js, enabling AI to read and update documentation.

Documentation

WikiJS MCP Server

An MCP server that connects MCP clients to your Wiki.js instance.

It supports both local connections over stdio and remote connections using the official MCP Streamable HTTP transport, making it suitable for local MCP clients as well as remotely hosted clients.

Prerequisites

  • Python 3.10+
  • A Wiki.js instance with API access enabled
  • A Wiki.js API key (Administration > API Access > New API Key)

Installation

pip install wikijs-mcp

For local development:

git clone https://github.com/Ho3pLi/wikijs-mcp-http.git
cd wikijs-mcp-http
pip install -e .

Configuration

Wiki.js

VariableDefaultDescription
WIKIJS_URLrequiredBase URL of your Wiki.js instance
WIKIJS_API_KEYrequired for stdio/single-key modeLegacy/default Wiki.js API key. Kept server-side and never returned by tools
WIKIJS_GRAPHQL_ENDPOINT/graphqlWiki.js GraphQL endpoint path
WIKIJS_READ_ONLYfalseWhen true, mutation tools are disabled
VariableDefaultDescription
---------------------------------------------------------------------------
WIKIJS_URLrequiredBase URL of your Wiki.js instance
WIKIJS_API_KEYrequiredWiki.js API key
WIKIJS_GRAPHQL_ENDPOINT/graphqlWiki.js GraphQL endpoint path
WIKIJS_READ_ONLYfalseWhen true, mutation tools are disabled

The Wiki.js API key is used only by the MCP server to communicate with Wiki.js. It remains server-side and is never returned or exposed to MCP clients.

Streamable HTTP

VariableDefaultDescription
MCP_HOST127.0.0.1Host interface for HTTP mode
MCP_PORT8000Port for HTTP mode
MCP_PATH/mcpMCP Streamable HTTP endpoint path
MCP_ALLOWED_HOSTS127.0.0.1:*,localhost:*Comma-separated Host header allowlist
MCP_ALLOWED_ORIGINShttp://127.0.0.1:*,http://localhost:*Comma-separated Origin header allowlist

Cloudflare Access multi-user authorization, for remote Streamable HTTP deployments:

VariableDefaultDescription
WIKIJS_CF_ACCESS_ISSUERunsetCloudflare Access JWT issuer, usually https://<team-name>.cloudflareaccess.com
WIKIJS_CF_ACCESS_AUDIENCEunsetCloudflare Access application audience tag
WIKIJS_CF_ACCESS_JWKS_URLunsetCloudflare Access JWKS URL, usually https://<team-name>.cloudflareaccess.com/cdn-cgi/access/certs
WIKIJS_AUTH_USERSunsetUser email to credential profile mapping
WIKIJS_AUTH_PROFILESunsetCredential profile to Wiki.js API-key environment variable mapping

The server does not bind to 0.0.0.0 by default. For production, put HTTPS/authentication in front of the local HTTP listener. The server intentionally does not bind to 0.0.0.0 by default.

For remote deployments, the recommended setup is to keep the MCP server listening locally and expose it through an HTTPS reverse proxy and, when appropriate, an authentication layer.

Choosing a transport

WikiJS MCP supports two MCP transports.

stdio

Use stdio when the MCP client can start the MCP server locally.

This is typically the simplest option for local clients such as Claude Code or other desktop/development tools.

MCP Client
    │
   stdio
    │
    ▼
WikiJS MCP
    │
  GraphQL
    │
    ▼
 Wiki.js

Streamable HTTP

Use Streamable HTTP when the MCP server needs to run independently or be accessed remotely.

This is useful for hosted MCP clients or when you want to run a single MCP server alongside your Wiki.js infrastructure.

Remote MCP Client
        │
      HTTPS
        │
        ▼
 Reverse Proxy / Auth
        │
        ▼
127.0.0.1:8000/mcp
        │
        ▼
    WikiJS MCP
        │
      GraphQL
        │
        ▼
      Wiki.js

Both transports expose the same Wiki.js tools.

Running

Local / stdio

stdio is the default transport:

WIKIJS_URL=https://wiki.example.com \
WIKIJS_API_KEY=... \
wikijs-mcp

Equivalent explicit form:

WIKIJS_URL=https://wiki.example.com \
WIKIJS_API_KEY=... \
wikijs-mcp --transport stdio

Remote / Streamable HTTP

WIKIJS_URL=https://wiki.example.com \
WIKIJS_API_KEY=... \
MCP_HOST=127.0.0.1 \
MCP_PORT=8000 \
MCP_PATH=/mcp \
wikijs-mcp --transport streamable-http

This exposes a standards-compliant MCP endpoint at:

http://127.0.0.1:8000/mcp

The endpoint is intended to be exposed through HTTPS infrastructure for remote access.

Do not commit credentials or expose the Wiki.js API key to clients.

When deploying behind a reverse proxy with a public hostname, explicitly allow that hostname and its browser origin:

MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_PATH=/mcp
MCP_ALLOWED_HOSTS=127.0.0.1:*,localhost:*,mcp.example.com
MCP_ALLOWED_ORIGINS=http://127.0.0.1:*,http://localhost:*,https://mcp.example.com

The MCP Python SDK enforces DNS rebinding protection for HTTP transports.

Cloudflare Access multi-user mode

By default, both stdio and Streamable HTTP use the single WIKIJS_API_KEY.

For a remote MCP protected by Cloudflare Access, you can enable multi-user mode. The server validates the Cf-Access-Jwt-Assertion header, extracts the authenticated email, maps it to a credential profile, then uses the Wiki.js API key from that profile only for the current MCP request. It does not mutate the global config or reuse a client with a changed authorization header.

Example:

WIKIJS_URL=https://wiki.example.com
WIKIJS_CF_ACCESS_ISSUER=https://example.cloudflareaccess.com
WIKIJS_CF_ACCESS_AUDIENCE=0000000000000000000000000000000000000000000000000000000000000000
WIKIJS_CF_ACCESS_JWKS_URL=https://example.cloudflareaccess.com/cdn-cgi/access/certs

WIKIJS_AUTH_USERS=admin@example.com=admin,friend1@example.com=friends,friend2@example.com=friends
WIKIJS_AUTH_PROFILES=admin=WIKIJS_API_KEY_ADMIN,friends=WIKIJS_API_KEY_FRIENDS

WIKIJS_API_KEY_ADMIN=fake-admin-api-key
WIKIJS_API_KEY_FRIENDS=fake-friends-api-key

JSON object syntax is also accepted for the mappings:

WIKIJS_AUTH_USERS={"admin@example.com":"admin","friend@example.com":"friends"}
WIKIJS_AUTH_PROFILES={"admin":"WIKIJS_API_KEY_ADMIN","friends":"WIKIJS_API_KEY_FRIENDS"}

Do not put Wiki.js API keys directly in WIKIJS_AUTH_USERS or WIKIJS_AUTH_PROFILES; profiles reference environment variable names only. Multiple users can share one profile, and the Wiki.js API key assigned to that profile should be associated with the corresponding Wiki.js group. Wiki.js remains the source of truth for page permissions and Page Rules.

When multi-user mode is configured in Streamable HTTP mode:

  • Missing or invalid Cf-Access-Jwt-Assertion is rejected.
  • Expired assertions, wrong issuer, and wrong audience are rejected.
  • Authenticated users without a mapping are rejected.
  • Missing profile definitions or missing API-key environment variables are rejected.
  • The server does not fall back to WIKIJS_API_KEY for remote authenticated requests.

In stdio, local use remains unchanged and uses WIKIJS_API_KEY.

In Cloudflare, the Access application audience tag is visible in the Access application settings. The issuer and JWKS URL are based on your team domain:

WIKIJS_CF_ACCESS_ISSUER=https://<team-name>.cloudflareaccess.com
WIKIJS_CF_ACCESS_JWKS_URL=https://<team-name>.cloudflareaccess.com/cdn-cgi/access/certs

To add a new Wiki.js group/API key:

  1. Create or select the Wiki.js group and Page Rules in Wiki.js.
  2. Create a Wiki.js API key associated with that group.
  3. Store the key in a new environment variable, for example WIKIJS_API_KEY_PARTNERS.
  4. Add a profile entry, for example partners=WIKIJS_API_KEY_PARTNERS.
  5. Map one or more Cloudflare Access user emails to partners.

Read-only mode

Keep that protection enabled. Do not use *, disable DNS rebinding protection, or spoof the Host header in nginx merely to bypass validation.

Reverse proxy example

A typical production deployment keeps WikiJS MCP bound to 127.0.0.1 and exposes /mcp through a reverse proxy.

Example nginx configuration:

server {
    listen 443 ssl;
    server_name mcp.example.com;

    # TLS configuration omitted for brevity.

    location /mcp {
        proxy_pass http://127.0.0.1:8000/mcp;

        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_buffering off;
    }
}

With this setup:

https://mcp.example.com/mcp
            │
            ▼
           nginx
            │
            ▼
http://127.0.0.1:8000/mcp
            │
            ▼
        WikiJS MCP

Authentication and access control should normally be handled in front of the MCP server when exposing it publicly.

For example, an identity-aware proxy, OAuth-capable gateway, VPN, or equivalent access-control layer can sit between the remote MCP client and nginx/MCP endpoint.

Read-only mode

WikiJS MCP can expose Wiki.js content without allowing clients to modify it.

Enable read-only mode with:

WIKIJS_READ_ONLY=true wikijs-mcp --transport streamable-http

When enabled, mutation tools return an MCP-visible error before contacting Wiki.js:

  • wiki_create_page
  • wiki_update_page
  • wiki_move_page
  • wiki_delete_page

Read-only tools continue to work normally.

This can be useful when exposing a Wiki.js knowledge base to remote or third-party MCP clients that should only be able to retrieve information.

MCP client examples

Claude Code / stdio

claude mcp add wikijs \
  --scope user \
  -e WIKIJS_URL=https://your-wiki.com \
  -e WIKIJS_API_KEY=your-api-key \
  -- pipx run wikijs-mcp

Generic stdio client

{
  "mcpServers": {
    "wikijs": {
      "command": "pipx",
      "args": ["run", "wikijs-mcp"],
      "env": {
        "WIKIJS_URL": "https://your-wiki.com",
        "WIKIJS_API_KEY": "your-api-key",
        "WIKIJS_DEFAULT_LOCALE": "en"
      }
    }
  }
}

Remote MCP clients

Clients that support MCP Streamable HTTP can connect to the public endpoint exposed by your reverse proxy:

https://mcp.example.com/mcp

The exact configuration depends on the MCP client being used.

The remote client does not need access to the Wiki.js API key. Authentication to Wiki.js is handled entirely by the WikiJS MCP server.

Locale configuration

Page operations need a locale. Without a locale hint, the server resolves one in this order:

  1. The explicit locale / destination_locale tool argument.
  2. The optional WIKIJS_DEFAULT_LOCALE environment variable.
  3. The wiki's primary locale (queried once per client from the instance).
  4. A hard fallback of en.

Pages usually resolve to the locale of your wiki automatically. The en fallback only applies when neither an explicit locale, WIKIJS_DEFAULT_LOCALE nor the wiki's primary locale can be determined. Set WIKIJS_DEFAULT_LOCALE to the primary locale of your wiki (e.g. de) to make the resolution deterministic without a round-trip to the wiki. Earlier releases hard-coded en even when the wiki's primary locale differed, which created pages in the wrong locale; those pages never reached Git storage and later move/delete failed with ENOENT: stat /data/repo/...md. update_page preserves the page's current locale unless an explicit locale is passed.

Asset upload usage

Assets (files, images) are uploaded via the Wiki.js v2 multipart endpoint POST {WIKIJS_URL}/u. The MCP server exposes:

  • wiki_upload_asset(local_path, folder_path, folder_id) — upload a local file. Missing folders in folder_path are created on demand. Returns the sanitized filename, the asset path, the public URL and a ready-to-paste markdown link.
  • wiki_list_assets(folder_path, folder_id, kind) — list files (ALL, IMAGE, BINARY).
  • wiki_create_asset_folder(slug, parent_path, parent_id, name) — create a folder.
  • wiki_rename_asset(asset_id, filename) / wiki_delete_asset(asset_id) — rename/delete a file.

Example for an agent prompt:

Upload /tmp/report-2026.pdf to team/manuals and embed it in the page team/manuals/report on the wiki.

Permission notes

  • Listing/reading assets requires the read:assets permission.
  • Uploading and creating folders requires write:assets.
  • Renaming and deleting assets requires manage:assets.
  • Assets are served at GET /{assetPath} and are not accessible to anonymous (guest) users — guests receive a 403 unless the asset's path is made public in Wiki.js.

Slug / filename behavior (documented, not worked around)

Wiki.js lowercases asset folder slugs (assets.createFolder runs sanitize(slug).toLowerCase()). The MCP client walks and creates folder paths with lowercased slugs, exactly as the server stores them. Uploaded filenames are sanitized server-side to lowercase with spaces/,/;/# replaced by underscores (e.g. Report Final (2).PDF → report_final_2_.pdf); the client mirrors this so it can report the expected final names.

Tools

ToolDescription
wiki_searchFull-text search across all wiki pages
wiki_get_pageGet a page by path or ID, with optional metadata_only and include_render modes
wiki_list_pagesList pages with optional tag filtering, sort order and locale filter
wiki_get_treeGet the hierarchical folder/page tree structure
wiki_create_pageCreate a new page
wiki_update_pageUpdate a page via full replacement or surgical find-and-replace (edits)
wiki_move_pageMove a page to a new path and/or locale, with post-move verification
wiki_delete_pageDelete a page
wiki_list_tagsList all tags used across the wiki
wiki_get_site_infoGet wiki site metadata (title, description, host)
wiki_get_historyGet page edit history with pagination
wiki_get_versionRetrieve a specific historical version of a page
wiki_upload_assetUpload a local file as a wiki asset (returns markdown link)
wiki_list_assetsList assets in a folder, optionally filtered by kind
wiki_create_asset_folderCreate an asset folder (slug is lowercased)
wiki_rename_assetRename an asset (keep the same extension)
wiki_delete_assetDelete an asset

Security considerations

When using Streamable HTTP:

  • Keep the MCP server bound to 127.0.0.1 unless you specifically need otherwise.
  • Use HTTPS for remote access.
  • Put authentication or access control in front of publicly reachable MCP endpoints.
  • Keep MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS restricted to expected hosts and origins.
  • Keep DNS rebinding protection enabled.
  • Never expose the Wiki.js API key to MCP clients.
  • Consider enabling WIKIJS_READ_ONLY=true when write access is not required.

The MCP server acts as the trusted intermediary between MCP clients and the Wiki.js GraphQL API.

Development

pip install -e .
pip install pytest pytest-asyncio pytest-cov pytest-mock pytest-xdist ruff

pytest
ruff check .

License

MIT