# 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)
```bash
# 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
```bash
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)
```bash
# 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:
```json
{
  "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`):
```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`

```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:
```bash
git clone https://github.com/cahaseler/wikijs-mcp.git
cd wikijs-mcp
```

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

3. Copy the environment template:
```bash
cp env.example .env
```

4. Edit `.env` with your WikiJS credentials

### Local WikiJS Instance

To run a local WikiJS instance for testing:

```bash
# 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
```bash
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.

```bash
# 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

# 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`:
```bash
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):
```bash
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.