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.
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.
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.1Move 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