Server

Overview

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

Anki

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).

Trilium

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.

Files

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:

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).

Access

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).

NixOS module

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";
};