TriliumNext (trilium-mcp)

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

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