trilium-mcp

trilium-mcp

Um servidor MCP que permite que agentes de IA (Claude Desktop, Claude Code, qualquer cliente compatível com MCP) leiam e escrevam em uma base de conhecimento TriliumNext auto-hospedada por meio de sua ETAPI.

Binário Go estático único. Sem dependências em tempo de execução. Comunica-se com seu Trilium local via HTTP(S) e com o cliente via stdio.

Por quê

TriliumNext é uma forte base de conhecimento pessoal: árvore de notas com atributos (rótulos, relações) que funcionam como colunas de tabela / faixas de quadro / eventos de calendário. Este MCP expõe a fatia certa da ETAPI para que um agente possa:

• Capturar conteúdo em suas notas (listas de leitura, decisões, despejos de pesquisa).
• Manter "tabelas" estruturadas criando notas-como-linhas sob um pai e marcando-as com rótulos-como-colunas.
• Pesquisar sua base de conhecimento existente e alimentar trechos de volta em uma conversa.

É intencionalmente mínimo: dez ferramentas, ~600 linhas de Go, zero abstrações inteligentes.

Ferramentas

Ferramenta	Propósito
create_note	Criar uma nota (opcionalmente sob um pai, com rótulos de uma só vez).
batch_create_notes	Criar muitas notas em uma única chamada — economiza a sobrecarga de esquema por chamada durante reestruturações.
get_note	Buscar metadados da nota; opcionalmente incluir o conteúdo do corpo.
get_note_subtree	Buscar recursivamente uma nota + descendentes até N níveis como uma árvore aninhada — substitui N+1 chamadas get_note.
update_note	Atualização parcial: inclua apenas os campos que deseja alterar; campos omitidos permanecem como estão.
append_content	Anexar texto ao corpo com um separador configurável.
delete_note	Excluir uma nota e sua subárvore.
batch_delete_notes	Excluir muitas notas; falhas parciais não interrompem o restante.
move_note	Reatribuir um pai a uma nota em duas chamadas ETAPI (em vez da antiga dança ler-recriar-excluir).
clone_note	Adicionar a nota sob um pai adicional — links multi-pai nativos do Trilium.
delete_branch	Remover um link pai-filho sem excluir a nota (des-clonar).
search_notes	Pesquisa Trilium completa (#label, ~relation, note.title %= "regex", escopo por ancestral, etc.).
add_label	Anexar um rótulo (#key=value) — atua como uma "coluna" em visualizações de coleção.
add_relation	Anexar uma relação (~name → noteId) — como uma chave estrangeira entre notas.
remove_attribute	Remover um rótulo ou relação pelo seu id de atributo.
list_attributes	Listar todos os rótulos e relações em uma nota.

Início rápido

1. Execute o TriliumNext

Se você ainda não tem um:

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

docker compose up -d

Abra http://localhost:8092/, conclua o assistente de configuração e depois Opções → ETAPI → Criar novo token ETAPI. Copie o token (mostrado apenas uma vez).

2. Instale o trilium-mcp

Binário pré-compilado (recomendado) — baixe o arquivo correto em Releases.

A partir do código-fonte com Go 1.23+:

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

Com Docker (sem Go no host):

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

3. Configure

Copie .env.example para .env ao lado do binário:

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

Ou passe o mesmo como variáveis de ambiente reais — o servidor lê qualquer uma das formas.

4. Registre com seu 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 — adicione a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou o equivalente no seu sistema operacional:

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

Reinicie o cliente. As dez ferramentas devem aparecer como trilium__*.

Padrões de uso

"Banco de dados" de notas (o recurso matador)

As visualizações de coleção do Trilium (Tabela / Quadro / Calendário) renderizam os filhos de qualquer nota com base em rótulos compartilhados. Portanto, uma "tabela" é apenas uma nota pai + notas filhas + um esquema de rótulos consistente:

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

Um agente a popula assim:

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

Alterne a visualização do pai para Tabela (ou Quadro por status, ou Calendário por um rótulo de data) na interface do Trilium e você terá um banco de dados sem nunca sair das notas.

Log somente anexação

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

append_content é não destrutivo — útil para diários diários, logs de decisões, despejos de ideação.

Folha de referência de pesquisa do Trilium

• #tag — a nota tem o rótulo tag.
• #status=active — rótulo é igual a.
• #rating>=8 — comparação numérica.
• ~author.title *= "Clear" — seguir uma relação, corresponder ao título do alvo da relação.
• note.title %= "^Re:" — regex no título.
• note.content *= "kubernetes" — substring no corpo.
• #status=active OR #status=pending — booleano.
• Combine com ancestor_note_id para limitar a uma subárvore.

Referência completa: Documentação de pesquisa do Trilium.

Variáveis de ambiente

Variável	Padrão	Observações
TRILIUM_URL	obrigatório	URL base da sua instância Trilium, ex.: http://localhost:8092. O caminho /etapi é adicionado automaticamente, mas uma barra final /etapi é tolerada e removida (então http://localhost:8092/etapi também funciona). Aceita múltiplas URLs separadas por vírgulas — o servidor tenta na ordem e recorre à próxima em erros de transporte (DNS/conexão/timeout). Erros HTTP como 404 são retornados imediatamente sem nova tentativa. Exemplo: http://192.168.0.10:8092,https://memo.example.com (LAN rápida primeiro, fallback público).
TRILIUM_TOKEN	obrigatório	Token ETAPI das configurações do Trilium
TRILIUM_HTTP_TIMEOUT_SECONDS	30	Timeout por requisição
TRILIUM_MCP_LOG	info	off / info / debug. Os logs são gravados em stderr (stdout é reservado para o fluxo JSON-RPC do MCP). info mostra uma linha por chamada de ferramenta com nome + duração + ok/erro. debug também mostra os argumentos da requisição e uma prévia truncada da resposta.

Compilando a partir do código-fonte

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

Compilação cruzada (ex.: para macOS a partir do Linux):

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

Notas de segurança

• O servidor lê TRILIUM_TOKEN do ambiente. Trate-o como uma senha — qualquer pessoa com ele pode ler e escrever toda a sua base de conhecimento. Mantenha .env fora do git (está em .gitignore).
• O binário fala apenas com a URL do Trilium configurada. Ele não faz chamadas externas, não grava logs em disco e não abre portas de escuta.
• HTTPS funciona automaticamente (o binário inclui os CAs do sistema quando executado no host; a imagem Docker inclui ca-certificates).

Contribuindo

PRs são bem-vindos. Direções úteis:

• Transmitir grandes corpos de notas em vez de armazenar em buffer.
• Ferramentas move_note / clone_note.
• Operações em lote (add_label_to_many).
• Recursos da ETAPI v2 conforme o TriliumNext os adiciona.
• Testes contra um contêiner TriliumNext efêmero.

Para mudanças substanciais, abra uma issue primeiro para discutir o formato.

Licença

MIT.

trilium-mcp é um projeto independente; não é endossado nem afiliado ao projeto TriliumNext. O TriliumNext em si é AGPL-3.0; este servidor MCP fala com ele apenas por sua ETAPI pública.