# mcp-server-wikijs

[![CI](https://github.com/margus/wikijs-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/margus/wikijs-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mcp-server-wikijs.svg)](https://pypi.org/project/mcp-server-wikijs/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-server-wikijs.svg)](https://pypi.org/project/mcp-server-wikijs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io) server that lets Claude (or any MCP client)
manage a **[Wiki.js](https://js.wiki/)** instance through its **GraphQL admin API** —
read and write pages, manage navigation and groups, and trigger Git storage syncs.

> Published on PyPI as **`mcp-server-wikijs`**; the source repo is
> [`margus/wikijs-mcp`](https://github.com/margus/wikijs-mcp). The admin focus (navigation,
> groups, Git sync, raw GraphQL) sets it apart from content-authoring Wiki.js MCP servers.

> **How it works:** MCP does *not* run inside Wiki.js. This is a small stdio server your
> MCP client launches locally; it talks to `https://<your-wiki>/graphql`. If your Wiki.js
> is on a private network, the machine running this needs network reach to it.

## Tools

| Tool | What it does |
|------|--------------|
| `execute_graphql(query, variables?)` | Run any Wiki.js GraphQL query/mutation (escape hatch) |
| `list_pages(locale?, limit?)` | List pages (id, locale, path, title) |
| `get_page(path?, locale?, id?)` | Get a page's content + metadata |
| `create_page(path, title, content, …)` | Create a page |
| `update_page(id, content?, title?, …)` | Update a page — only passed fields change |
| `delete_page(id)` | Delete a page |
| `get_navigation()` | Current nav mode + tree |
| `set_navigation_mode(mode)` | `NONE` / `TREE` / `MIXED` / `STATIC` |
| `list_groups()` / `get_group(id)` | Groups + their permissions/page rules |
| `trigger_git_sync()` | Re-sync the Git storage target (re-import content repo) |

## Prerequisites

1. A running **Wiki.js 2.x** instance.
2. An **API key**: *Administration → API Access →* enable the API *→ New API Key*
   (full access; the 2.x API isn't finely scoped). Copy the token.

## Quick start

Run it on demand with [`uvx`](https://docs.astral.sh/uv/) (no install) — set the two
environment variables and go:

```bash
export WIKIJS_URL="https://wiki.example.com"
export WIKIJS_TOKEN="your-api-key"
uvx mcp-server-wikijs
```

Or install it:

```bash
pip install mcp-server-wikijs     # or: uv tool install mcp-server-wikijs
mcp-server-wikijs
```

The server speaks MCP over **stdio**, so running it directly just waits for a client —
that's expected. Wire it into a client below.

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `WIKIJS_URL` | ✅ | Base URL of your Wiki.js instance (e.g. `https://wiki.example.com`). The GraphQL endpoint is `<URL>/graphql`. |
| `WIKIJS_TOKEN` | ✅ | Wiki.js API key. Aliases also accepted: `WIKIJS_API_TOKEN`, `WIKI_JS_MCP_API_TOKEN`. |

For standalone runs you can instead drop a `.env` next to where you launch it
(`cp .env.example .env`); it's loaded automatically.

## Register with an MCP client

### Claude Code

```bash
claude mcp add wikijs --env WIKIJS_URL=https://wiki.example.com --env WIKIJS_TOKEN=your-api-key -- uvx mcp-server-wikijs
```

…or add it to `.mcp.json` / your settings:

```json
{
  "mcpServers": {
    "wikijs": {
      "command": "uvx",
      "args": ["mcp-server-wikijs"],
      "env": {
        "WIKIJS_URL": "https://wiki.example.com",
        "WIKIJS_TOKEN": "your-api-key"
      }
    }
  }
}
```

> **Tip:** keep secrets out of committed files — reference an env var that's already in
> your shell, e.g. `"WIKIJS_TOKEN": "${WIKIJS_TOKEN}"`, and start the client from a shell
> where it's set.

### Claude Desktop

Add the same block to `claude_desktop_config.json`
(*Settings → Developer → Edit Config*), then restart Claude Desktop.

## Examples

Once registered, ask your assistant things like:

- *"List every page under `clients/` in the `en` locale."*
- *"Create a page at `guides/onboarding` titled 'Onboarding' with this content: …"*
- *"Update page 31 — append a 'Troubleshooting' section, leave everything else."*
- *"Trigger a Git sync so the wiki re-imports the content repo."*

## Security

The Wiki.js API key is **full-admin** — treat it as a privileged credential. Keep it in
your secrets manager / environment, never commit it, and revoke or rotate it anytime from
*Wiki.js → API Access*. Every write tool acts with that key's full authority, so review
mutations before approving them.

## Development

```bash
git clone https://github.com/margus/wikijs-mcp
cd wikijs-mcp
uv sync                # install runtime + dev deps
uv run pytest          # run the test suite (no live wiki needed — httpx is mocked)
uv run ruff check .    # lint
```

The Wiki.js logic lives in `src/wikijs_mcp/client.py` (`WikiJSClient`), unit-tested against
`httpx.MockTransport`. `src/wikijs_mcp/server.py` is a thin layer of MCP tool wrappers over
it. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)