trilium-mcp
An MCP server that lets AI agents (Claude Desktop, Claude Code, any MCP-compatible client) read and write a self-hosted TriliumNext knowledge base over its ETAPI.
Single static Go binary. No runtime dependencies. Talks to your local Trilium over HTTP(S) and to the client over stdio.
Why
TriliumNext is a strong personal KB: tree-of-notes with attributes (labels, relations) that double as table columns / board lanes / calendar events. This MCP exposes the right slice of ETAPI so an agent can:
- Capture stuff into your notes (reading lists, decisions, research dumps).
- Maintain structured "tables" by creating notes-as-rows under a parent and tagging them with labels-as-columns.
- Search your existing KB and feed snippets back into a conversation.
It is intentionally minimal: ten tools, ~600 lines of Go, zero clever abstractions.
Tools
| Tool | Purpose |
|---|---|
create_note | Create a note (optionally under a parent, with labels in one shot). |
batch_create_notes | Create many notes in one call — saves per-call schema overhead during restructuring. |
get_note | Fetch note metadata; optionally include body content. |
get_note_subtree | Recursively fetch a note + descendants up to N levels as a nested tree — replaces N+1 get_note calls. |
update_note | Partial update: include only the fields you want to change; omitted fields stay as-is. |
append_content | Append text to the body with a configurable separator. |
delete_note | Delete a note and its subtree. |
batch_delete_notes | Delete many notes; partial failures don't stop the rest. |
move_note | Re-parent a note in two ETAPI calls (vs the old read-recreate-delete dance). |
clone_note | Add the note under an additional parent — Trilium-native multi-parent links. |
delete_branch | Remove one parent-child link without deleting the note (un-clone). |
search_notes | Full-power Trilium search (#label, ~relation, note.title %= "regex", ancestor scoping, etc.). |
add_label | Attach a label (#key=value) — acts as a "column" in collection views. |
add_relation | Attach a relation (~name → noteId) — like a foreign key between notes. |
remove_attribute | Remove a label or relation by its attribute id. |
list_attributes | List all labels and relations on a note. |
Quick start
1. Run TriliumNext
If you don't already have one:
# docker-compose.yml
services:
trilium:
image: triliumnext/notes:latest
ports:
- "8092:8080"
volumes:
- ./data:/home/node/trilium-data
docker compose up -d
Open http://localhost:8092/, finish the setup wizard, then Options → ETAPI → Create new ETAPI token. Copy the token (shown only once).
2. Install trilium-mcp
Pre-built binary (recommended) — grab the right archive from Releases.
From source with Go 1.23+:
go install github.com/OVDEN13/trilium-mcp@latest
With Docker (no Go on host):
git clone https://github.com/OVDEN13/trilium-mcp && cd trilium-mcp
docker build -t trilium-mcp .
3. Configure
Copy .env.example to .env next to the binary:
TRILIUM_URL=http://localhost:8092
TRILIUM_TOKEN=your-etapi-token-here
# Optional:
# TRILIUM_HTTP_TIMEOUT_SECONDS=30
Or pass the same as real environment variables — the server reads either.
4. Register with your MCP client
Claude Code (CLI):
claude mcp add --scope user trilium /path/to/trilium-mcp \
--env TRILIUM_URL=http://localhost:8092 \
--env TRILIUM_TOKEN=your-token
Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:
{
"mcpServers": {
"trilium": {
"command": "/absolute/path/to/trilium-mcp",
"env": {
"TRILIUM_URL": "http://localhost:8092",
"TRILIUM_TOKEN": "your-token"
}
}
}
}
Restart the client. The ten tools should show up as trilium__*.
Usage patterns
"Database" of notes (the killer feature)
Trilium's collection views (Table / Board / Calendar) render any note's children based on shared labels. So a "table" is just a parent note + child notes + a consistent label schema:
Books (parent)
├── "Atomic Habits" #status=read #rating=9 #author=Clear
├── "Antifragile" #status=read #rating=8 #author=Taleb
└── "Деньги" #status=reading #author=Жонсон
An agent populates it like this:
// 1. Create the row
create_note({
parent_note_id: "<id of Books>",
title: "Atomic Habits",
labels: { "status": "read", "rating": "9", "author": "Clear" }
})
// 2. Query rows later
search_notes({ query: "#status=read #rating>=8", ancestor_note_id: "<id of Books>" })
Flip the parent's view to Table (or Board by status, or Calendar by a date label) in the Trilium UI and you have a database without ever leaving notes.
Append-only log
append_content({ note_id: "<journal id>", content: "Decided to ship v0.2 on Monday." })
append_content is non-destructive — handy for daily journals, decision logs, ideation dumps.
Trilium search cheat sheet
#tag— note has labeltag.#status=active— label equals.#rating>=8— numeric comparison.~author.title *= "Clear"— follow a relation, match relation target's title.note.title %= "^Re:"— regex on title.note.content *= "kubernetes"— substring in body.#status=active OR #status=pending— boolean.- Combine with
ancestor_note_idto scope to a subtree.
Full reference: Trilium search docs.
Environment variables
| Var | Default | Notes |
|---|---|---|
TRILIUM_URL | required | Base URL of your Trilium instance, e.g. http://localhost:8092. The /etapi path is added automatically, but a trailing /etapi is tolerated and stripped (so http://localhost:8092/etapi also works). Accepts multiple URLs separated by commas — the server tries them in order and falls back to the next one on transport errors (DNS/connection/timeout). HTTP errors like 404 are returned immediately without retry. Example: http://192.168.0.10:8092,https://memo.example.com (fast LAN first, public fallback). |
TRILIUM_TOKEN | required | ETAPI token from Trilium settings |
TRILIUM_HTTP_TIMEOUT_SECONDS | 30 | Per-request timeout |
TRILIUM_MCP_LOG | info | off / info / debug. Logs are written to stderr (stdout is reserved for the MCP JSON-RPC stream). info shows one line per tool call with name + duration + ok/error. debug also shows the request arguments and a truncated preview of the response. |
Building from source
git clone https://github.com/OVDEN13/trilium-mcp
cd trilium-mcp
go build -ldflags="-s -w" -o trilium-mcp .
Cross-compile (e.g. for macOS from Linux):
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -o trilium-mcp-darwin-arm64 .
Security notes
- The server reads
TRILIUM_TOKENfrom env. Treat it like a password — anyone with it can read and write your entire KB. Keep.envout of git (it is in.gitignore). - The binary speaks only to your configured Trilium URL. It does not phone home, log to disk, or open any listening ports.
- HTTPS works automatically (the binary ships with system CAs when run from the host; the Docker image includes
ca-certificates).
Contributing
PRs welcome. Useful directions:
- Stream large note bodies instead of buffering.
move_note/clone_notetools.- Bulk operations (
add_label_to_many). - ETAPI v2 features as TriliumNext adds them.
- Tests against an ephemeral TriliumNext container.
For substantive changes, please open an issue first to discuss the shape.
License
MIT.
trilium-mcp is an independent project; it is not endorsed by or affiliated with the TriliumNext project. TriliumNext itself is AGPL-3.0; this MCP server talks to it only over its public ETAPI.