kioku MCP

Overview

MCP server that gives agents typed tools over the user’s Anki collection (anki_*) and Trilium notes (trilium_*), for Open WebUI, Claude Code and OpenCode. How it works, the Open WebUI setup (skills, the Kioku model, the API key), recovery and development are documented in its repo: https://git.yhkze.net/yuuhikaze/kioku (docs/). This page covers only this deployment.

Modules: modules/features/kioku-mcp.nix (server), modules/features/kioku-client.nix (desktop, laptop)

flowchart LR
  subgraph server [Server 10.100.0.1]
    OWUI[Open WebUI backend] -->|loopback| K[kioku-mcp 127.0.0.1:8099]
    TR[Traefik entrypoint wireguard :8453] --> K
    K -->|sync protocol| SYNC[anki-sync-server :27701]
    K -->|ETAPI| TRI[Trilium :8067]
    K -.->|read-only| WORK[(/var/lib/open-terminal/work)]
    SB[Open Terminal sandbox] -.->|/work| WORK
  end
  WS[Desktop, laptop] -->|WireGuard| TR
  DEV[Anki desktop, AnkiDroid] -->|anki.yhkze.net| SYNC

Values — the hostname and WireGuard port come from values/kioku.nix; the sandbox workspace (services.kioku-mcp.sandbox) from values/open-terminal.nix, shared with open-terminal.nix.

Access — no public route. Open WebUI calls the loopback port. Desktop and laptop reach kioku.yhkze.net:8453, a name that exists only in their /etc/hosts (pointing at 10.100.0.1) so the wildcard certificate applies. An nftables rule admits only the desktop and laptop WireGuard addresses on that port (values/network-details.nix), which keeps out the Talos nodes that are also WireGuard peers.

Clients — kioku-client.nix configures Claude Code and OpenCode with the server’s URL and token, and installs kioku-upload, which sends an image to the server for the tools to use.

Versions — anki-sync-server and kioku’s dependencies come from the anki-suite nixpkgs input, so the anki library inside kioku always speaks the sync server’s protocol. A routine update holds anki-suite back: it moves kioku’s own source to the repo’s HEAD, never the Anki stack underneath it.

Setup

Secrets — add to hosts/server/secrets/secrets.yaml:

kioku-mcp:
    # openssl rand -hex 32
    token: <token>
    # Trilium → Options → ETAPI → Create new ETAPI token, named "kioku-mcp"
    trilium-token: <etapi token>

Add the same kioku-mcp/token to hosts/desktop/secrets/secrets.yaml and hosts/laptop/secrets/secrets.yaml.

Open WebUI — register the tool server and publish the skills and the Kioku model as the kioku repo’s docs/open-webui.md describes. The tool server’s bearer token is kioku-mcp/token, and sandbox_dir in kioku’s secrets.toml is the mountPoint of values/open-terminal.nix.

Updates

Update the server after a change in the kioku repo; rebuild desktop and laptop too when kioku-client.nix changed:

nix flake update kioku
rebuild 10.100.0.1

Move the Anki stack (sync server and kioku together) only deliberately, then run kioku’s VM test against the new pin before deploying:

nix flake update anki-suite