wikijs-mcp

An MCP server for managing Wiki.js 2.x pages: search, read, create, update, move, delete, browse version history, and list assets — all through the Wiki.js GraphQL API.

Tools

| Tool | Description | | ---------------------- | -------------------------------------------------------- | | search_pages | Full-text search across pages. | | list_pages | List pages with ordering, tag, and locale filters. | | get_page | Fetch a page by id or path, including its content. | | get_page_tree | Browse the page hierarchy. | | list_tags | List all tags, or search tags matching a query. | | create_page | Create a new page. | | update_page | Partially update a page by id. | | move_page | Move/rename a page (requires manage:pages permission). | | delete_page | Delete a page (destructive). | | get_page_history | Fetch a page's version history trail. | | get_page_version | Fetch the content of a specific historical version. | | restore_page_version | Restore a page to a prior version. | | list_assets | List asset folders and files (read-only). |

Quick start (stdio)

Add the server to Claude Code with claude mcp add:

claude mcp add wikijs -e WIKIJS_URL=https://wiki.example.com -e WIKIJS_TOKEN=your-api-key-here -- npx @sondt2709/wikijs-mcp

For Claude Desktop, Cursor, or any other MCP client that reads a JSON config, add:

{
  "mcpServers": {
    "wikijs": {
      "command": "npx",
      "args": ["@sondt2709/wikijs-mcp"],
      "env": {
        "WIKIJS_URL": "https://wiki.example.com",
        "WIKIJS_TOKEN": "your-api-key-here"
      }
    }
  }
}

Getting an API key

1. Log in to your Wiki.js instance as an administrator.
2. Go to Administration → API Access.
3. Toggle Enable API on.
4. Click New API Key, give it a name and expiration, and grant it the permissions your workflow needs (read:pages at minimum; write:pages, manage:pages, and manage:system for creating/updating/moving/deleting pages).
5. Copy the generated token — it's shown only once — and use it as WIKIJS_TOKEN.

Configuration

| Variable / flag | Default | Description | | --------------------------- | ------- | ------------------------------------------------------------------- | | WIKIJS_URL / --url | — | Base URL of your Wiki.js instance (required). | | WIKIJS_TOKEN / --token | — | API key from Administration → API Access (required). | | TRANSPORT / --transport | stdio | stdio or http. | | PORT / --port | 3000 | Port to listen on when TRANSPORT=http. | | LOG_LEVEL / --log-level | info | pino log level: fatal, error, warn, info, debug, trace. |

CLI flags take precedence over environment variables. See .env.example for a template.

HTTP / Docker mode

Run the server as a long-lived streamable-HTTP service instead of stdio — useful for sharing one instance across multiple clients, or running behind a reverse proxy.

cp .env.example .env   # set WIKIJS_URL and WIKIJS_TOKEN
docker compose up

This builds the image from the included Dockerfile and starts the server with TRANSPORT=http on port 3000:

• MCP endpoint: http://localhost:3000/mcp
• Health check: http://localhost:3000/healthz

Point your MCP client at the /mcp endpoint instead of spawning the process directly.

MCP Inspector

To poke at the server interactively:

pnpm inspect

This builds the project and launches the MCP Inspector against the stdio transport.

To inspect an HTTP deployment instead, start the server with docker compose up (or TRANSPORT=http pnpm dev), then run npx @modelcontextprotocol/inspector on its own and connect the Inspector UI to http://localhost:3000/mcp using the "Streamable HTTP" transport option.

Development

pnpm install       # install dependencies
pnpm dev           # run from source with --watch
pnpm lint          # eslint
pnpm typecheck     # tsc --noEmit
pnpm format        # prettier --write
pnpm build         # bundle to dist/

End-to-end tests run against a real, disposable Wiki.js instance in Docker:

pnpm e2e:wiki:up       # start local Wiki.js in Docker
pnpm e2e:bootstrap     # headless setup: admin account + API key + e2e/.env
pnpm test:e2e          # build + run the e2e suite
pnpm e2e:wiki:down     # tear down the container and its data

See e2e/setup.md for details, including a manual setup fallback if the bootstrap script fails.

Lefthook runs eslint --fix and prettier on staged files at pre-commit, and typecheck + build at pre-push. It's installed automatically via the prepare script after pnpm install.

Releasing

Pushing a tag matching v* (e.g. v0.2.0) triggers .github/workflows/release.yml, which lints, typechecks, builds, and publishes the package to npm with provenance.

The NPM_TOKEN repository secret must be set (an npm automation token with publish access to @sondt2709/wikijs-mcp) before pushing a release tag, or the workflow will fail at the publish step.

License

MIT