TriliumNext (trilium-mcp)

io.github.OVDEN13Published by GitHub account OVDEN13v0.1.5Updated Oct 24, 2026

Read and write a self-hosted TriliumNext knowledge base over its ETAPI.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

MCP server that lets an AI assistant read and write a self-hosted TriliumNext knowledge base over its ETAPI, creating, searching, moving and tagging notes.

What you can do
  • Create notes, including batch creation under a parent with labels in one call
  • Read note metadata, bodies and whole subtrees as nested trees
  • Update, append to, move, clone and delete notes or branches
  • Search the knowledge base with Trilium query syntax, optionally scoped to a subtree
  • Attach, list and remove labels and relations that act as columns or links
When to use it
Useful when you keep notes in a self-hosted TriliumNext instance and want an assistant to capture research, decisions or reading lists, maintain label-based table or board views, and pull snippets from your existing notes into a conversation.
Requirements
A running TriliumNext instance reachable over HTTP(S) and an ETAPI token created in Trilium options, supplied as TRILIUM_TOKEN. TRILIUM_URL is required and accepts comma-separated URLs for failover. Optional TRILIUM_HTTP_TIMEOUT_SECONDS and TRILIUM_MCP_LOG. Runs as a local binary or Docker image over stdio; no runtime dependencies.
Before you install
TRILIUM_TOKEN grants full read and write access to the entire knowledge base, so treat it like a password and keep it out of version control. Tools can create, update, move, clone and delete notes and their subtrees, and batch deletes continue past partial failures. Debug logging can print request arguments and response previews to stderr.

Installation

In SourceWeft

  1. Open TriliumNext (trilium-mcp) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolPurpose
create_noteCreate a note (optionally under a parent, with labels in one shot).
batch_create_notesCreate many notes in one call — saves per-call schema overhead during restructuring.
get_noteFetch note metadata; optionally include body content.
get_note_subtreeRecursively fetch a note + descendants up to N levels as a nested tree — replaces N+1 get_note calls.
update_notePartial update: include only the fields you want to change; omitted fields stay as-is.
append_contentAppend text to the body with a configurable separator.
delete_noteDelete a note and its subtree.
batch_delete_notesDelete many notes; partial failures don't stop the rest.
move_noteRe-parent a note in two ETAPI calls (vs the old read-recreate-delete dance).
clone_noteAdd the note under an additional parent — Trilium-native multi-parent links.
delete_branchRemove one parent-child link without deleting the note (un-clone).
search_notesFull-power Trilium search (#label, ~relation, note.title %= "regex", ancestor scoping, etc.).
add_labelAttach a label (#key=value) — acts as a "column" in collection views.
add_relationAttach a relation (~name → noteId) — like a foreign key between notes.
remove_attributeRemove a label or relation by its attribute id.
list_attributesList all labels and relations on a note.

Quick start

1. Run TriliumNext

If you don't already have one:

yaml
# docker-compose.ymlservices:  trilium:    image: triliumnext/notes:latest    ports:      - "8092:8080"    volumes:      - ./data:/home/node/trilium-data
bash
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+:

bash
go install github.com/OVDEN13/trilium-mcp@latest

With Docker (no Go on host):

bash
git clone https://github.com/OVDEN13/trilium-mcp && cd trilium-mcpdocker build -t trilium-mcp .

3. Configure

Copy .env.example to .env next to the binary:

env
TRILIUM_URL=http://localhost:8092TRILIUM_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):

bash
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:

json
{  "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:

jsonc
// 1. Create the rowcreate_note({  parent_note_id: "<id of Books>",  title: "Atomic Habits",  labels: { "status": "read", "rating": "9", "author": "Clear" }})
// 2. Query rows latersearch_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

jsonc
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 label tag.
  • #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_id to scope to a subtree.

Full reference: Trilium search docs.

Environment variables

VarDefaultNotes
TRILIUM_URLrequiredBase 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_TOKENrequiredETAPI token from Trilium settings
TRILIUM_HTTP_TIMEOUT_SECONDS30Per-request timeout
TRILIUM_MCP_LOGinfooff / 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

bash
git clone https://github.com/OVDEN13/trilium-mcpcd trilium-mcpgo build -ldflags="-s -w" -o trilium-mcp .

Cross-compile (e.g. for macOS from Linux):

bash
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -o trilium-mcp-darwin-arm64 .

Security notes

  • The server reads TRILIUM_TOKEN from env. Treat it like a password — anyone with it can read and write your entire KB. Keep .env out 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_note tools.
  • 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.

Source: README.md at commit a3a3289

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.5LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts