Wiki.js MCP Server: Technical Details

Technical details of the Wiki.js MCP Server: structure, GraphQL operations used, how an update works, error handling, shutdown and development.

Deutsche Version

Back to overview

Technical Details

Structure

Path	Purpose
`src/index.ts`	Entry point: loads the `.env`, checks the variables, registers the 7 tools, starts the stdio transport, handles signals
`src/constants.ts`	fixed limits (timeout, truncation, sizes, pagination)
`src/schemas/index.ts`	Zod schemas for all tool inputs
`src/services/client.ts`	`WikiJsClient`: sends the GraphQL requests
`src/services/error-handler.ts`	uniform error and success responses
`src/tools/*.ts`	one file per tool
`tests/update-page.test.ts`	Vitest tests for the update behaviour

The package is an ES module ("type": "module"); entry point and bin entry is dist/index.js.

Technologies

TypeScript, compiled with tsc to dist/
MCP SDK @modelcontextprotocol/sdk (McpServer, stdio transport)
Zod for input validation
dotenv to load the .env
Vitest for tests
HTTP through the fetch built into Node.js, no additional HTTP library

GraphQL operations used

All requests are sent as POST with a JSON body and Authorization: Bearer <token> to WIKIJS_API_URL.

Tool	Operation	Note
`wikijs_list_pages`	`pages.list`	returns all pages, locale filter and pagination happen in the server
`wikijs_get_page`	`pages.single(id)` or `pages.singleByPath(path, locale)`	without tags
`wikijs_search_pages`	`pages.search(query)`	locale filter in the server
`wikijs_create_page`	`pages.create`	with `path`, `title`, `content`, `description`, `editor`, `isPublished`, `isPrivate`, `locale`, `tags`
`wikijs_update_page`	`pages.update`	with `id`, `content`, `title`, `description`, `isPublished`, `tags`
`wikijs_delete_page`	`pages.delete(id)`
`wikijs_move_page`	`pages.move(id, destinationPath, destinationLocale)`

Path-based update, delete and move calls first resolve the path to an ID with pages.singleByPath.

How wikijs_update_page works

sequenceDiagram
    participant C as MCP client
    participant S as MCP server
    participant W as Wiki.js

    C->>S: wikijs_update_page
    S->>S: Zod validation
    S->>W: singleByPath if only path given
    S->>W: single(id) if content, title or description is missing
    S->>W: list if tags is missing
    S->>W: update with all fields
    W-->>S: responseResult
    S-->>C: success or error

The pages.update mutation needs a value for title, description, content and tags; that is why the server fills missing fields from the page's current state.

Error handling

Every tool handler catches errors and returns isError: true with {"success": false, "error": ..., "tool": ...}. The server does not crash on them.
Validation errors name the field and the reason.
An HTTP status outside 2xx results in Wiki.js API request failed: HTTP error! status: <code>.
GraphQL errors result in Wiki.js API request failed: GraphQL request failed: <messages>.
If Wiki.js reports succeeded: false in responseResult, the message is Failed to create page: ..., Failed to update page: ..., Failed to delete page: ... or Failed to move page: ... followed by the text from Wiki.js.
If a request exceeds 30 seconds you get Request timed out. Please try again.
The server does not retry requests automatically.

Shutdown

On SIGINT, SIGTERM, unhandled errors and promise rejections the server closes the MCP connection and exits. An EPIPE (client closed the connection) is not logged.

Development

npm install
npm run dev         # tsx in watch mode
npm run build       # compile to dist/
npm run typecheck   # type check without output
npm test            # Vitest

The CI builds and type-checks the project with Node.js 18, 20 and 22.