# wiki-js-mcp

An [MCP](https://modelcontextprotocol.io) server for [Wiki.js](https://js.wiki) — lets AI agents create, read, update, search, list, and move wiki pages via the Wiki.js GraphQL API.

## Tools

| Tool | Description |
|------|-------------|
| `wiki_get_page` | Read a page's content and metadata by path |
| `wiki_create_page` | Create a new page with markdown content |
| `wiki_update_page` | Update content, metadata, or patch a named section |
| `wiki_search_pages` | Full-text search — returns title, path, description, tags |
| `wiki_list_pages` | List pages with an optional path-prefix filter |
| `wiki_move_page` | Rename or restructure a page path |

All tools return `{"success": bool, "error": str | null, ...}` and never raise — the calling agent decides how to handle failures.

### Section patching

`wiki_update_page` supports surgical updates to named sections without touching the rest of the page. Fence any block in your wiki content with HTML comments:

```html
<!-- OSIA:AUTO:watchlist -->
Content managed by the AI agent goes here.
<!-- /OSIA:AUTO:watchlist -->
```

Then call:

```python
wiki_update_page(
    path="desks/geopolitical-and-security",
    section="watchlist",
    section_content="- Benjamin Netanyahu (🔴 Critical)\n- ...",
)
```

The markers and surrounding content are left untouched.

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- A running Wiki.js 2.x instance with a valid API key

## Installation

```bash
git clone https://github.com/osianet/wiki-js-mcp.git
cd wiki-js-mcp
uv sync
```

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

```dotenv
WIKIJS_URL=http://localhost:3000/graphql
WIKIJS_API_KEY=your-api-key-here
```

Generate an API key at `https://your-wiki/a/api-keys` in the Wiki.js admin panel.

## Usage

### Standalone (stdio)

```bash
uv run wiki-mcp
```

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wiki-js": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/wiki-js-mcp", "wiki-mcp"],
      "env": {
        "WIKIJS_URL": "http://localhost:3000/graphql",
        "WIKIJS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### With Claude Code

Add to your project's `.claude/settings.json` or `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "wiki-js": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/wiki-js-mcp", "wiki-mcp"]
    }
  }
}
```

## Development

```bash
uv sync --extra dev

# Lint
uv run ruff check wiki_mcp.py

# Format
uv run ruff format wiki_mcp.py

# Type check
uv run pyright wiki_mcp.py

# Tests
uv run pytest
```

## License

MIT — see [LICENSE](LICENSE).