kioku-mcp is an MCP server (Streamable HTTP at /mcp)
that sits next to an Anki sync server and a Trilium server. Agents call
its tools; it is the only thing that writes to either.
flowchart LR
subgraph host [Server]
OWUI[Open WebUI backend] -->|loopback| K[kioku-mcp :8099]
RP[Reverse proxy, private network] --> K
K -->|sync protocol| SYNC[Anki sync server]
K -->|ETAPI| TRI[Trilium]
K -.->|read-only| WORK[(Sandbox workspace)]
SB[Open Terminal sandbox] -.-> WORK
end
WS[Coding agents on workstations] --> RP
DEV[Anki desktop, AnkiDroid] -->|sync| SYNC
Replica — the server keeps its own copy of the
collection under /var/lib/kioku-mcp/anki and syncs it with
the sync server as one more device of the account. Agents edit
flashcards without the desktop app running; the desktop app and
AnkiDroid only review, sync, and receive the agents’ changes.
First start — the service downloads the collection
from the sync server (logged as sync: full download). The
sync server must already hold the collection, which it does as soon as
any device has synced.
Writes — every write syncs before and after,
preceded by a backup (colpkg) in
/var/lib/kioku-mcp/anki/backups. Deletions take explicit
note ids and confirm=true, never a search query.
Note types — the tools never modify an existing note type: adding, removing or reordering fields or templates forces a one-way full sync that can discard reviews on other devices. New note types are fine. Existing ones are changed in the desktop app.
Full sync — when another device forces a full sync, the service downloads the collection again if it has nothing unsynced. Otherwise it refuses, and every Anki tool returns the error until the conflict is resolved (reference Operations).
Plain ETAPI client. Every content overwrite saves a native revision first, and deleted notes stay recoverable until Trilium erases them.
The tools write code notes with mime
text/x-markdown by default, the user’s standard format.
They refuse to edit canvas notes (Excalidraw scene data),
doc notes and the root note.
Images for cards and notes never pass through the model as data: an
image as base64 would be generated token by token.
anki_add_media and trilium_add_attachment take
a reference in their source argument instead:
<mountPoint>/<path> — a file the model
created in Open WebUI’s Open Terminal sandbox, on the same host. The
service gets read-only access to the sandbox workspace (the module’s
sandbox option) and refuses paths that resolve outside it
(.., symlinks). The sandbox gets no network path to the
service.upload:<id> — a file posted to
/upload with the bearer token, which returns the id.
Uploads land in /var/lib/kioku-mcp/uploads and expire after
24 h.kioku-upload <file> on a workstation does the
upload and prints the source (the nixos repo’s
kioku-client.nix installs it):
kioku-upload circuit.png
# {"source":"upload:66d4febfeed67454"}Files are limited to 20 MB. trilium_add_attachment
returns the tag that embeds the attachment, <img> for
an image and a looping <video> for a video;
skills/kioku/MEDIA.md covers where it goes in notes and
cards. Re-uploading a file under the same title replaces the previous
attachment in place (same attachmentId, so embeds keep working) and
deletes any extra old copies, instead of accumulating versions.
trilium_delete_attachment removes an attachment by id — for
old versions that survived under a different title (e.g. after renaming
figura.png to figura.svg).
Every request except /healthz needs the bearer token
from tokenFile; wrong or missing tokens get 401. The
service binds to loopback, and systemd denies it every address outside
ipAddressAllow (localhost by default). Clients on other
machines go through a reverse proxy, whose hostname must be in
allowedHosts (DNS rebinding protection).
The flake exports nixosModules.default, which defines
services.kioku-mcp. The nixos repo’s
modules/features/kioku-mcp.nix is the reference
deployment.
| Option | Purpose |
|---|---|
host, port |
Listen address, 127.0.0.1:8099 by default |
allowedHosts |
Host headers accepted besides localhost,
e.g. kioku.example.net:* |
tokenFile |
Bearer token every client sends |
anki.endpoint, anki.user,
anki.passwordFile |
Sync server URL and the account it syncs as |
trilium.url, trilium.tokenFile |
Trilium base URL and an ETAPI token |
sandbox.hostDir, sandbox.mountPoint |
Open Terminal workspace on the host and inside the sandbox;
null disables sandbox paths |
ipAddressAllow |
Addresses the service may talk to |
Anki version — the anki pylib comes from nixpkgs’
anki.lib output, never from PyPI. The host pins this
flake’s nixpkgs to the same nixpkgs as its
anki-sync-server, so the replica always speaks the sync
server’s protocol:
kioku = {
url = "git+https://git.yhkze.net/yuuhikaze/kioku";
inputs.nixpkgs.follows = "anki-suite";
};