wikijs-mcp-server-cahaseler

WikiJS MCP Server

A Model Context Protocol (MCP) server that provides integration with WikiJS, allowing AI assistants to search and retrieve content from your WikiJS knowledge base.

Overview

This MCP server enables AI assistants to interact with WikiJS instances by providing tools to:

• Search for pages by query string
• Retrieve pages by ID
• Retrieve pages by path and locale
• Get all pages from the wiki
• Edit pages (when enabled)

Installation

Using npx (published package)

# NOTE: the binary is named wikijs-mcp-edit, not after the package name:
npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit

This always runs the latest published version from npm. For the current feature branch (see git remote), build from source instead.

From source

git clone <your-clone-url>
cd wikijs-mcp
pnpm install      # or: npm install
pnpm run build    # or: npm run build

Configuration

Claude Code

Method 1: Using the CLI (Recommended)

# Add as a user-scoped server (available across all projects)
claude mcp add wikijs \
  -e WIKIJS_URL=https://your-wiki.example.com \
  -e WIKIJS_API_KEY=your-api-key \
  -- npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit

# Or, when running from a local clone (uses your build instead of the
# published package):
claude mcp add wikijs \
  -e WIKIJS_URL=https://your-wiki.example.com \
  -e WIKIJS_API_KEY=your-api-key \
  -- node /absolute/path/to/wikijs-mcp/build/index.js

# Or with edit functionality enabled
claude mcp add wikijs \
  -e WIKIJS_URL=https://your-wiki.example.com \
  -e WIKIJS_API_KEY=your-api-key \
  -e WIKIJS_ENABLE_EDIT=true \
  -- npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit

Method 2: Project-scoped configuration

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "wikijs": {
      "command": "npx",
      "args": ["-p", "@cahaseler/wikijs-mcp", "wikijs-mcp-edit"],
      "env": {
        "WIKIJS_URL": "https://your-wiki.example.com",
        "WIKIJS_API_KEY": "your-api-key",
        "WIKIJS_ENABLE_EDIT": "false"
      }
    }
  }
}

Cursor

Add to your Cursor settings (.cursor/settings.json):

{
  "mcpServers": {
    "wikijs-mcp": {
      "command": "npx",
      "args": ["-p", "@cahaseler/wikijs-mcp", "wikijs-mcp-edit"],
      "env": {
        "WIKIJS_URL": "https://your-wiki.example.com",
        "WIKIJS_API_KEY": "your-api-key",
        "WIKIJS_ENABLE_EDIT": "false"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wikijs-mcp": {
      "command": "npx",
      "args": ["-p", "@cahaseler/wikijs-mcp", "wikijs-mcp-edit"],
      "env": {
        "WIKIJS_URL": "https://your-wiki.example.com",
        "WIKIJS_API_KEY": "your-api-key",
        "WIKIJS_ENABLE_EDIT": "false"
      }
    }
  }
}

Getting a WikiJS API Key

1. Log into your WikiJS instance as an administrator
2. Go to Administration > API Access
3. Enable the API if not already enabled
4. Click New API Key
5. Give it a name (e.g., "MCP Server")
6. Select Full Access or configure specific permissions
7. Set an appropriate expiration date
8. Copy the generated key immediately (it won't be shown again)

Environment Variables

Variable	Description	Required	Default
WIKIJS_URL	URL of your WikiJS instance (without /graphql)	Yes	-
WIKIJS_API_KEY	WikiJS API key	Yes	-
WIKIJS_ENABLE_EDIT	Enable page editing functionality	No	false
WIKIJS_DEFAULT_LOCALE	Locale used when building page URLs	No	en

Available Tools

Once configured, the following tools will be available (10 read / 6 write):

Read (always available):

• search_pages - Search for pages by query string
  • Parameters: query (required), path (optional), locale (optional)
• get_page_by_id - Retrieve a specific page by its ID (full page incl. rendered content)
  • Parameters: id (required)
• get_page_by_path - Retrieve a page by its path and locale
  • Parameters: path (required), locale (required)
• get_all_pages - List pages with optional filters
  • Parameters: limit (optional, max 500), locale (optional), tags (optional)
• get_page_history - Revision history of a page
  • Parameters: id (required), offsetPage (optional), offsetSize (optional, max 200)
• get_page_version - A specific revision of a page
  • Parameters: pageId (required), versionId (required)
• get_page_tree - Page tree of the site
  • Parameters: locale (required), mode (optional, FOLDERS/PAGES/ALL, default PAGES), path (optional), parent (optional), includeAncestors (optional)
• list_tags - List all tags
• search_tags - Search tags
  • Parameters: query (required)
• get_page_links - Link graph of all pages for a locale
  • Parameters: locale (required)

Write (only available when WIKIJS_ENABLE_EDIT=true):

• create_page - Create a new WikiJS page
  • Parameters: title, content, description, path (required); editor (default markdown), isPublished (default true), isPrivate (default false), locale (optional, default en), tags (optional)
• edit_page - Edit a WikiJS page by its ID. Full-document replace for content; all other fields are optional — omitted fields keep their existing values (metadata is never wiped by omission)
  • Parameters: id, content (required); title, description, path, editor, isPublished, isPrivate, locale, tags (optional)
• move_page - Move a page to a new path/locale
  • Parameters: id, destinationPath, destinationLocale (required)
• delete_page - Delete a page
  • Parameters: id (required)
• restore_page_version - Restore a previous version
  • Parameters: pageId, versionId (required)
• convert_page_editor - Convert a page to another editor type
  • Parameters: id, editor (required e.g. markdown, visual)

Development

Prerequisites

• Node.js 18+ at runtime for the built server (engines in package.json)
• Node.js 20.19+ for development tooling (eslint 10 requires ^20.19 || ^22.13 || >=24)
• npm or pnpm
• Docker (for local WikiJS testing)

Setup

1. Clone the repository:

   git clone https://github.com/cahaseler/wikijs-mcp.git
   cd wikijs-mcp
   

   1. Install dependencies (pnpm primary, npm works too): bash pnpm install # or: npm install

2. Copy the environment template:

   cp env.example .env
   

   1. Edit .env with your WikiJS credentials

   Local WikiJS Instance

   To run a local WikiJS instance for testing:

   # Start WikiJS and PostgreSQL
   docker-compose up -d
   
   # The instance will be available at http://localhost:3000
   # Follow the setup wizard to create an admin account
   

Building

pnpm run build      # or: npm run build
pnpm run clean      # alternative: make clean

# or via make (uses pnpm internally)
make build

Testing the MCP Server

The server is a stdio MCP server — it is started by an MCP client, not manually as a daemon.

# Quick smoke without a wiki connection: expect output = version from package.json
node build/index.js --version

# Run it manually (it then waits, silently, for MCP protocol frames on stdio):
WIKIJS_URL=http://localhost:3000 WIKIJS_API_KEY=your-key node build/index.js

# The built server auto-loads .env from the current working directory (dotenv),
# so from the repo root this is sufficient: node build/index.js — provided
# you created .env via the Setup steps above. Note: env variables take
# precedence over .env values.

# Interactive verify the tools without a full client setup (browser UI, default http://localhost:6274):
npx @modelcontextprotocol/inspector node build/index.js      # pnpm: pnpm dlx @modelcontextprotocol/inspector node build/index.js

Missing env vars abort the server immediately with WIKIJS_URL and WIKIJS_API_KEY must be set on stderr.

Security Considerations

• API Key Storage: Never commit your API key to version control
• Edit Permissions: The edit functionality is disabled by default. Only enable it if you trust the environment where the MCP server is running
• Scope Permissions: When creating the WikiJS API key, consider using the minimum required permissions instead of full access

Troubleshooting

"WIKIJS_URL and WIKIJS_API_KEY must be set"

Ensure your environment variables are properly configured. Check your .env file or the environment variables in your MCP client configuration.

"Failed to update page: Unauthorized"

Your API key may be expired or lack the necessary permissions. Create a new API key with appropriate permissions.

sh: wikijs-mcp-edit: not found when running npx @cahaseler/wikijs-mcp

npx fetched the package but looked for a binary named after the package. The binary is called wikijs-mcp-edit:

npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit

GraphQL errors during development

If you modify the GraphQL queries, regenerate the types (requires WIKIJS_URL reachable — it introspects your Wiki.js instance):

pnpm codegen     # or: npm run codegen

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.