trilium-mcp

trilium-mcp

Un servidor MCP que permite a los agentes de IA (Claude Desktop, Claude Code, cualquier cliente compatible con MCP) leer y escribir en una base de conocimiento TriliumNext autoalojada a través de su ETAPI.

Binario Go estático único. Sin dependencias de ejecución. Se comunica con tu Trilium local a través de HTTP(S) y con el cliente a través de stdio.

Por qué

TriliumNext es una sólida base de conocimiento personal: árbol de notas con atributos (etiquetas, relaciones) que funcionan como columnas de tabla / carriles de tablero / eventos de calendario. Este MCP expone la porción adecuada de ETAPI para que un agente pueda:

• Capturar cosas en tus notas (listas de lectura, decisiones, volcados de investigación).
• Mantener "tablas" estructuradas creando notas como filas bajo un padre y etiquetándolas con etiquetas como columnas.
• Buscar en tu base de conocimiento existente y devolver fragmentos a la conversación.

Es intencionalmente mínimo: diez herramientas, ~600 líneas de Go, cero abstracciones ingeniosas.

Herramientas

Herramienta	Propósito
create_note	Crear una nota (opcionalmente bajo un padre, con etiquetas de una sola vez).
batch_create_notes	Crear muchas notas en una sola llamada — ahorra sobrecarga de esquema por llamada durante la reestructuración.
get_note	Obtener metadatos de la nota; opcionalmente incluir contenido del cuerpo.
get_note_subtree	Obtener recursivamente una nota + descendientes hasta N niveles como un árbol anidado — reemplaza N+1 llamadas a get_note.
update_note	Actualización parcial: incluye solo los campos que deseas cambiar; los campos omitidos permanecen igual.
append_content	Añadir texto al cuerpo con un separador configurable.
delete_note	Eliminar una nota y su subárbol.
batch_delete_notes	Eliminar muchas notas; los fallos parciales no detienen el resto.
move_note	Re-parentar una nota en dos llamadas ETAPI (en lugar del antiguo baile de leer-recrear-eliminar).
clone_note	Añadir la nota bajo un padre adicional — enlaces multi-padre nativos de Trilium.
delete_branch	Eliminar un enlace padre-hijo sin borrar la nota (des-clonar).
search_notes	Búsqueda completa de Trilium (#label, ~relation, note.title %= "regex", alcance de ancestros, etc.).
add_label	Adjuntar una etiqueta (#key=value) — actúa como una "columna" en vistas de colección.
add_relation	Adjuntar una relación (~name → noteId) — como una clave foránea entre notas.
remove_attribute	Eliminar una etiqueta o relación por su id de atributo.
list_attributes	Listar todas las etiquetas y relaciones en una nota.

Inicio rápido

1. Ejecutar TriliumNext

Si aún no tienes uno:

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

docker compose up -d

Abre http://localhost:8092/, completa el asistente de configuración, luego Opciones → ETAPI → Crear nuevo token ETAPI. Copia el token (se muestra solo una vez).

2. Instalar trilium-mcp

Binario precompilado (recomendado) — descarga el archivo correcto desde Releases.

Desde el código fuente con Go 1.23+:

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

Con Docker (sin Go en el host):

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

3. Configurar

Copia .env.example a .env junto al binario:

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

O pásalas como variables de entorno reales — el servidor lee cualquiera de las dos.

4. Registrar con tu cliente MCP

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 — añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en tu sistema operativo:

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

Reinicia el cliente. Las diez herramientas deberían aparecer como trilium__*.

Patrones de uso

"Base de datos" de notas (la característica estrella)

Las vistas de colección de Trilium (Tabla / Tablero / Calendario) renderizan los hijos de cualquier nota basándose en etiquetas compartidas. Así que una "tabla" es solo una nota padre + notas hijas + un esquema de etiquetas consistente:

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

Un agente la llena así:

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

Cambia la vista del padre a Tabla (o Tablero por status, o Calendario por una etiqueta de fecha) en la interfaz de Trilium y tendrás una base de datos sin salir nunca de las notas.

Registro de solo añadir

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

append_content no es destructivo — útil para diarios diarios, registros de decisiones, volcados de ideas.

Hoja de referencia de búsqueda de Trilium

• #tag — la nota tiene la etiqueta tag.
• #status=active — la etiqueta es igual.
• #rating>=8 — comparación numérica.
• ~author.title *= "Clear" — seguir una relación, coincidir con el título del objetivo de la relación.
• note.title %= "^Re:" — regex en el título.
• note.content *= "kubernetes" — subcadena en el cuerpo.
• #status=active OR #status=pending — booleano.
• Combina con ancestor_note_id para limitar a un subárbol.

Referencia completa: Documentación de búsqueda de Trilium.

Variables de entorno

Var	Por defecto	Notas
TRILIUM_URL	requerido	URL base de tu instancia de Trilium, p. ej. http://localhost:8092. La ruta /etapi se añade automáticamente, pero un /etapi final se tolera y se elimina (así que http://localhost:8092/etapi también funciona). Acepta múltiples URLs separadas por comas — el servidor las prueba en orden y cae a la siguiente en errores de transporte (DNS/conexión/timeout). Errores HTTP como 404 se devuelven inmediatamente sin reintento. Ejemplo: http://192.168.0.10:8092,https://memo.example.com (LAN rápida primero, respaldo público).
TRILIUM_TOKEN	requerido	Token ETAPI de la configuración de Trilium
TRILIUM_HTTP_TIMEOUT_SECONDS	30	Tiempo de espera por solicitud
TRILIUM_MCP_LOG	info	off / info / debug. Los registros se escriben en stderr (stdout está reservado para el flujo JSON-RPC de MCP). info muestra una línea por llamada de herramienta con nombre + duración + ok/error. debug también muestra los argumentos de la solicitud y una vista previa truncada de la respuesta.

Compilar desde el código fuente

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

Compilación cruzada (p. ej. para macOS desde Linux):

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

Notas de seguridad

• El servidor lee TRILIUM_TOKEN de las variables de entorno. Trátalo como una contraseña — cualquiera que lo tenga puede leer y escribir toda tu base de conocimiento. Mantén .env fuera de git (está en .gitignore).
• El binario se comunica solo con tu URL de Trilium configurada. No llama a casa, no registra en disco, ni abre puertos de escucha.
• HTTPS funciona automáticamente (el binario incluye las CA del sistema cuando se ejecuta desde el host; la imagen Docker incluye ca-certificates).

Contribuciones

Se aceptan PRs. Direcciones útiles:

• Transmitir cuerpos de notas grandes en lugar de almacenarlos en búfer.
• Herramientas move_note / clone_note.
• Operaciones masivas (add_label_to_many).
• Características de ETAPI v2 a medida que TriliumNext las añada.
• Pruebas contra un contenedor TriliumNext efímero.

Para cambios sustanciales, por favor abre un issue primero para discutir la forma.

Licencia

MIT.

trilium-mcp es un proyecto independiente; no está respaldado ni afiliado con el proyecto TriliumNext. TriliumNext en sí es AGPL-3.0; este servidor MCP se comunica con él solo a través de su ETAPI público.