TriliumNext (trilium-mcp)

trilium-mcp

一个 MCP 服务，让 AI Agent（Claude Desktop、Claude Code，以及任何兼容 MCP 的客户端）通过 ETAPI 读写可自托管的 TriliumNext 知识库。

单个静态 Go 二进制文件。无需运行时依赖。通过 HTTP(S) 与本地 Trilium 通信，并通过标准输入输出与客户端通信。

为什么选择它

TriliumNext 是一款出色的个人知识库：以树状组织笔记，并通过属性（标签、关系）实现表格列、看板泳道和日历事件等功能。这个 MCP 服务提供了恰到好处的 ETAPI 功能，让 Agent 可以：

• 将内容收集到笔记中（阅读清单、决策、研究资料等）。
• 通过在某个父笔记下创建作为行的笔记，并用作为列的标签标记它们，维护结构化“表格”。
• 搜索现有知识库，并将摘要片段带回对话中。

它刻意保持精简：十个工具、约 600 行 Go 代码，没有多余的抽象。

工具

工具	用途
create_note	创建笔记（可指定父笔记，并一次性添加标签）。
batch_create_notes	一次调用创建多条笔记，重组时可减少每次调用的架构开销。
get_note	获取笔记元数据；可选择包含正文内容。
get_note_subtree	递归获取笔记及其后代，并按嵌套树结构返回，最多深入 N 层，替代 N+1 次 get_note 调用。
update_note	局部更新：只包含要更改的字段；省略的字段保持不变。
append_content	使用可配置的分隔符向正文追加文本。
delete_note	删除笔记及其子树。
batch_delete_notes	删除多条笔记；部分失败不会影响其余操作。
move_note	通过两次 ETAPI 调用重新指定笔记的父笔记（无需像以前那样先读取、再重建、最后删除）。
clone_note	将笔记添加到另一个父笔记下，使用 Trilium 原生的多父级链接。
delete_branch	移除一条父子链接，但不删除笔记（取消克隆）。
search_notes	使用完整功能的 Trilium 搜索（#label、~relation、note.title %= "regex"、祖先范围限定等）。
add_label	添加标签（#key=value），在集合视图中充当“列”。
add_relation	添加关系（~name → noteId），类似笔记之间的外键。
remove_attribute	根据属性 ID 移除标签或关系。
list_attributes	列出笔记上的所有标签和关系。

快速开始

1. 运行 TriliumNext

如果你还没有安装：

# docker-compose.yml
services:
  trilium:
    image: triliumnext/notes:latest
    ports:
      - "8092:8080"
    volumes:
      - ./data:/home/node/trilium-data

docker compose up -d

打开 http://localhost:8092/，完成设置向导，然后选择 Options → ETAPI → Create new ETAPI token。复制令牌（它只会显示一次）。

2. 安装 trilium-mcp

预构建二进制文件（推荐）——从 Releases 下载合适的压缩包。

从源码构建，需要 Go 1.23+：

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

使用 Docker（主机上无需安装 Go）：

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

3. 配置

将 .env.example 复制到二进制文件所在目录，并命名为 .env：

TRILIUM_URL=http://localhost:8092
TRILIUM_TOKEN=your-etapi-token-here
# Optional:
# TRILIUM_HTTP_TIMEOUT_SECONDS=30

也可以将相同配置作为实际环境变量传入——服务会读取这两种配置。

4. 向 MCP 客户端注册

Claude Code（命令行）：

claude mcp add --scope user trilium /path/to/trilium-mcp \
  --env TRILIUM_URL=http://localhost:8092 \
  --env TRILIUM_TOKEN=your-token

Claude Desktop——将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），或你所用操作系统中的相应文件：

{
  "mcpServers": {
    "trilium": {
      "command": "/absolute/path/to/trilium-mcp",
      "env": {
        "TRILIUM_URL": "http://localhost:8092",
        "TRILIUM_TOKEN": "your-token"
      }
    }
  }
}

重启客户端。此时应会显示这十个工具，名称为 trilium__*。

使用模式

笔记“数据库”（杀手级功能）

Trilium 的集合视图（表格／看板／日历）会根据共享标签显示任意笔记的子项。因此，“表格”只需一个父笔记、若干子笔记，以及统一的标签架构：

Books (parent)
├── "Atomic Habits"   #status=read    #rating=9   #author=Clear
├── "Antifragile"     #status=read    #rating=8   #author=Taleb
└── "Деньги"          #status=reading             #author=Жонсон

Agent 可以这样填充它：

// 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>" })

在 Trilium 界面中，将父笔记的视图切换为表格（或按 status 切换为看板，或按日期标签切换为日历），无需离开笔记即可获得数据库。

仅追加日志

append_content({ note_id: "<journal id>", content: "Decided to ship v0.2 on Monday." })

append_content 不会破坏现有内容，适用于每日日志、决策记录和创意随记。

Trilium 搜索速查表

• #tag — 笔记包含标签 tag。
• #status=active — 标签值相等。
• #rating>=8 — 数值比较。
• ~author.title *= "Clear" — 沿关系查找，并匹配关系目标的标题。
• note.title %= "^Re:" — 对标题进行正则匹配。
• note.content *= "kubernetes" — 在正文中进行子字符串匹配。
• #status=active OR #status=pending — 布尔逻辑。
• 与 ancestor_note_id 结合使用，可将范围限定为某个子树。

完整参考：Trilium 搜索文档。

环境变量

变量	默认值	说明
TRILIUM_URL	必填	Trilium 实例的基础 URL，例如 http://localhost:8092。会自动添加 /etapi 路径，但也允许并会去除末尾的 /etapi（因此 http://localhost:8092/etapi 也可用）。接受以逗号分隔的多个 URL——服务会按顺序尝试，遇到传输错误（DNS／连接／超时）时会回退到下一个 URL。HTTP 错误（如 404）会立即返回，不会重试。示例：http://192.168.0.10:8092,https://memo.example.com（优先使用快速局域网地址，失败时回退到公网地址）。
TRILIUM_TOKEN	必填	Trilium 设置中的 ETAPI 令牌
TRILIUM_HTTP_TIMEOUT_SECONDS	30	每个请求的超时时间
TRILIUM_MCP_LOG	info	off / info / debug。日志写入 stderr（stdout 专用于 MCP JSON-RPC 数据流）。info 会为每次工具调用显示一行日志，包含名称、耗时和成功／错误状态。debug 还会显示请求参数和截断后的响应预览。

从源代码构建

git clone https://github.com/OVDEN13/trilium-mcp
cd trilium-mcp
go build -ldflags="-s -w" -o trilium-mcp .

交叉编译（例如在 Linux 上为 macOS 编译）：

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

安全说明

• 服务从环境变量中读取 TRILIUM_TOKEN。请像对待密码一样保管它——任何拥有它的人都能读取和修改你的整个知识库。请勿将 .env 提交到 git（它已列在 .gitignore 中）。
• 二进制文件仅与已配置的 Trilium URL 通信。它不会向外发送数据，不会写入磁盘日志，也不会开放任何监听端口。
• HTTPS 可自动使用（在主机上运行时，二进制文件会使用系统 CA；Docker 镜像包含 ca-certificates）。

参与贡献

欢迎提交 PR。以下方向有助于改进：

• 对较大的笔记正文进行流式处理，而不是缓冲。
• 添加 move_note / clone_note 工具。
• 批量操作（add_label_to_many）。
• 随着 TriliumNext 增加 ETAPI v2 功能，跟进相关支持。
• 使用临时 TriliumNext 容器进行测试。

对于较大的改动，请先提交 issue，讨论具体方案。

许可证

MIT。

trilium-mcp 是独立项目；它未获 TriliumNext 项目认可，也与其无关联。TriliumNext 本身采用 AGPL-3.0 许可证；此 MCP 服务仅通过其公开的 ETAPI 与之通信。