wikijs-mcp

# wikijs-mcp

<!-- badges: start -->

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/wikijs-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/wikijs-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/wikijs-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/wikijs-mcp)
<a href="https://socket.dev/npm/package/@ni-c/wikijs-mcp"><img src="https://socket.dev/api/badge/npm/package/@ni-c/wikijs-mcp" alt="Socket supply-chain report" height="20"></a>
[![Glama score](https://glama.ai/mcp/servers/ni-c/wikijs-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/wikijs-mcp)
<br>
[![npm version](https://img.shields.io/npm/v/%40ni-c%2Fwikijs-mcp)](https://www.npmjs.com/package/@ni-c/wikijs-mcp)
[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fwikijs--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/wikijs-mcp/pkgs/container/wikijs-mcp)
[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
<br>
[![docs](https://img.shields.io/badge/docs-wikijs--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://wikijs-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
<!-- badges: end -->

<!-- The opening is three paragraphs in a fixed shape: what it IS, what it LETS A
     CLIENT DO, and how to make it smaller. Keep "Lets MCP clients like Claude Code,
     Claude Desktop or Codex …" verbatim — the family drifted into "It lets an AI
     assistant", "It gives a model" and "This server speaks" before it was pinned.

     There is NO standalone "Full documentation" line. The docs badge above links
     to the same page; the line existed in five different spellings and said
     nothing the badge did not. -->

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[Wiki.js](https://js.wiki), the self-hosted wiki that keeps its pages as markdown and exposes everything through one GraphQL endpoint.

Lets MCP clients like Claude Code, Claude Desktop or Codex search, read and edit wiki pages — and, if you let them, manage its assets, comments, users, groups and maintenance jobs.

Sixty-two tools is the ceiling, not the floor:
`WIKIJS_ALLOW_TOOLS=essential` registers a curated seven
instead, and a model picks the right tool far more reliably from
seven than from sixty-two — see
[choosing which tools load](#choosing-which-tools-load).

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
     picks the variant that matches its own theme toggle. npm strips <picture> and
     <source> when it sanitises the README and keeps the <img>, which is why that
     fallback brings its own dark card instead of relying on a media query.
     All three URLs must stay absolute: npm does not resolve repo-relative paths. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://wikijs-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://wikijs-mcp.ni-c.de/architecture-light.svg">
  <img src="https://wikijs-mcp.ni-c.de/architecture.svg" alt="An MCP client talking to wikijs-mcp over stdio, which calls the Wiki.js GraphQL endpoint" width="800">
</picture>

<!-- Absolute, like the diagram: npm does not resolve repo-relative paths, and a
     recording nobody sees is a recording that was not worth making. -->
<img src="https://wikijs-mcp.ni-c.de/demo.gif" alt="Searching a wiki for text the built-in search cannot find, then being refused an ambiguous edit" width="800">

## What makes it different

**Finds text search cannot.** Wiki.js' default engine indexes titles and
descriptions only — so `search_pages` says which engine is running, and
`grep_pages` searches the actual text of pages.

**Will not clobber a colleague.** `update_page` compares against the moment you
read the page and refuses to overwrite an edit saved in between. Surgical edits
must match exactly once.

**Writes can be confined to part of the wiki.** `WIKIJS_ALLOWED_PATHS` limits the
writing page and asset tools to path prefixes, matched by path segment, while
reads stay unrestricted.

## Requirements

- Node.js ≥ 22
- A running **Wiki.js** instance and an API token

## Configuration

| Variable               | Required | Description                                                                                |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `WIKIJS_URL`           | yes      | Base URL of the wiki, e.g. `https://wiki.example.com`. A trailing `/graphql` is trimmed    |
| `WIKIJS_TOKEN`         | yes      | API key from Administration → API Access. `WIKIJS_API_KEY` is accepted as an alias         |
| `WIKIJS_LOCALE`        | no       | Locale assumed by page tools that are not given one (default `en`)                         |
| `WIKIJS_READ_ONLY`     | no       | `true`, `1` or `yes` registers only the read tools                                         |
| `WIKIJS_ALLOWED_PATHS` | no       | Comma-separated page path prefixes the write tools are confined to, e.g. `docs,team/notes` |
| `WIKIJS_ALLOW_TOOLS`   | no       | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset         |
| `WIKIJS_DENY_TOOLS`    | no       | Same syntax; removed from whatever `WIKIJS_ALLOW_TOOLS` left                               |
| `ELICITATION`          | no       | `false` replaces the approval dialog with the two-call token. **Not prefixed**             |
| `WIKIJS_INSECURE_TLS`  | no       | `true` accepts self-signed certificates (scoped to this connection)                        |

**The locale is part of a page's identity**, not a display preference: the same path
under `en` and `de` is two different pages. On a wiki set up in another language,
set `WIKIJS_LOCALE` or every lookup by path answers "not found". `list_locales`
reports what is installed.

**API keys are administrative.** Wiki.js offers "full access" or a group, and a
full-access key can rewrite every page and every account. `WIKIJS_READ_ONLY`,
`WIKIJS_ALLOWED_PATHS` and the key's own group permissions are three independent
ways to narrow that — see [SECURITY.md](SECURITY.md).

> **Use `https://`.** Over plain http the token travels unencrypted; the server
> prints a warning unless the host is local. For self-signed certificates prefer a
> proper internal CA over `WIKIJS_INSECURE_TLS`.

Without credentials the server still starts and lists its tools (so registries and
inspectors can introspect it), but every call fails with setup instructions instead
of reaching the API.

### Choosing which tools load

<!-- This heading is the anchor the opening paragraph links to. Keep the wording:
     it has to be #choosing-which-tools-load in every repository. -->

`WIKIJS_ALLOW_TOOLS` and `WIKIJS_DENY_TOOLS` take comma-separated
tool names; a trailing `*` matches a whole family. `essential` is a curated preset —
`search_pages`, `grep_pages`, `get_page`, `list_pages`, `get_page_tree`, `create_page` and `update_page`, which is what it takes to find, read and write a wiki page end to end — marked as such in the
[tool reference](https://wikijs-mcp.ni-c.de/reference/tools).

```sh
WIKIJS_ALLOW_TOOLS=essential
WIKIJS_ALLOW_TOOLS=get_page,search_pages,list_*
WIKIJS_DENY_TOOLS=delete_*,purge_page_history,set_api_state
```

An entry that matches no tool aborts startup and names it, so a typo cannot silently
hide a tool — an absent tool is not something anyone traces back to an environment
variable. A filtered tool is never registered, so it is absent from `tools/list` and
unknown to `tools/call` alike, exactly like a write tool under
`WIKIJS_READ_ONLY`.

If you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de) is
the other answer — its `/hub` endpoint replaces every server's tools with six
meta-tools.

### Confining writes to part of the wiki

`WIKIJS_ALLOWED_PATHS` limits the writing page and asset tools to a set of path
prefixes. Reads stay unrestricted, deliberately: a scope on reads turns a wiki into
a confusing half-wiki, and the API key's own page rules are the right place to hide
pages outright — they hide them from the web UI too.

```sh
WIKIJS_ALLOWED_PATHS=docs,team/notes
```

Matching is by path segment, so `docs` covers `docs/setup` and **not**
`docs-archive/old`. `move_page` checks both ends, so a page cannot be moved out of
the allowed area or into a protected one.

Asset writes are checked against the asset folder tree, which is a separate
namespace. The operations that cannot be confined to a prefix at all — all six
instance-wide maintenance tools, the tag tools, and comment edits, because
Wiki.js does not say which page a comment is on — refuse while the variable is
set rather than making a silent exception. That includes `flush_page_cache`,
`rebuild_page_tree` and `rebuild_search_index`, which lose nothing but still act
on the whole wiki.

## Installation

### Claude Code

```sh
claude mcp add wikijs-mcp -- npx -y @ni-c/wikijs-mcp
```

### Claude Desktop

```json
{
  "mcpServers": {
    "wikijs-mcp": {
      "command": "npx",
      "args": ["-y", "@ni-c/wikijs-mcp"],
      "env": {
        "WIKIJS_URL": "https://wiki.example.com",
        "WIKIJS_TOKEN": "…"
      }
    }
  }
}
```

### Codex

```toml
[mcp_servers.wikijs-mcp]
command = "npx"
args = ["-y", "@ni-c/wikijs-mcp"]
env = { WIKIJS_URL = "https://wiki.example.com", WIKIJS_TOKEN = "…" }
```

### Docker

```sh
docker run --rm -i \
  -e WIKIJS_URL=https://wiki.example.com \
  -e WIKIJS_TOKEN=… \
  ghcr.io/ni-c/wikijs-mcp
```

### Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web,
Cursor, LibreChat — reaches wikijs-mcp through [mcp-hub](https://mcp-hub.ni-c.de): o