Obsidian

Obsidian MCP

Um servidor local Model Context Protocol que permite que assistentes compatíveis com MCP leiam e modifiquem com segurança vaults do Obsidian explicitamente configurados.

A versão 2 suporta tanto MCP 2026-07-28 quanto clientes da era 2025 por padrão e requer Node.js 22 ou mais recente. Ela trabalha diretamente com arquivos Markdown, então o Obsidian não precisa estar aberto. O protocolo legado e a compatibilidade com caminhos posicionais v1 estão obsoletos e imprimem instruções exatas de migração no stderr.

[!IMPORTANT] Clientes MCP podem invocar ferramentas destrutivas. Faça backup de vaults importantes, revise os avisos de permissão do cliente e use pré-condições de revisão para notas editadas simultaneamente.

Início rápido

Node.js 22 ou mais recente é necessário:

node --version # v22 or newer

Execute com npx sem instalar o pacote globalmente. Fixar a versão principal recebe atualizações compatíveis 2.x sem cruzar automaticamente uma futura versão principal:

npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault

Configure um cliente MCP para iniciar o mesmo comando via stdio:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/vault"]
    }
  }
}

Alternativamente, instale o pacote globalmente e use "command": "obsidian-mcp" com os mesmos argumentos começando em "serve":

npm install -g obsidian-mcp@2

Cada vault já deve conter um diretório .obsidian e deve ser configurado usando um caminho absoluto.

Ambas as eras de protocolo são servidas a partir das mesmas definições de ferramentas. Após confirmar que seu cliente MCP negocia 2026-07-28, você pode optar pelo modo somente moderno adicionando "--legacy", "reject" a args.

Os IDs de vault usam letras minúsculas, dígitos, _ e -, devem começar com uma letra e são os valores que os assistentes passam para as ferramentas. Até dez vaults podem ser configurados. Repita --vault para expor mais de um vault:

obsidian-mcp serve \
  --vault work=/Users/me/Documents/WorkVault \
  --vault personal=/Users/me/Documents/PersonalVault

Locais de rede, removíveis, ocultos e sincronizados são permitidos porque um --vault explícito é tratado como autorização; as mesmas proteções de contenção se aplicam a todos os locais.

Princípios de design

• O acesso ao vault é explicitamente permitido na inicialização do processo.
• Cada caminho de ferramenta é relativo ao vault, verificado por segmento e bloqueado contra symlinks e estado reservado.
• As mutações de arquivo são registradas em diário, verificadas quanto a conflitos, substituídas atomicamente e revertidas como uma única transação.
• O servidor nunca escuta em uma interface de rede nem envia telemetria.
• O stdout é reservado exclusivamente para mensagens MCP; diagnósticos estruturados vão para o stderr.
• Os resultados são limitados, paginados quando apropriado e disponíveis tanto como texto quanto como conteúdo estruturado.

Ferramentas

Ferramenta	Finalidade
obsidian_list_vaults	Listar IDs de vault configurados sem expor caminhos do host.
obsidian_read_note	Ler uma página limitada de uma nota e retornar seu SHA-256 etag.
obsidian_create_note	Criar atomicamente uma nota sem sobrescrever.
obsidian_edit_note	Anexar, prefixar ou substituir o conteúdo exato da nota.
obsidian_delete_note	Mover uma nota para a lixeira MCP ou excluí-la permanentemente com confirmação explícita.
obsidian_move_note	Mover ou renomear uma nota e atualizar backlinks inequívocos transacionalmente.
obsidian_create_directory	Criar transacionalmente um diretório dentro de um vault.
obsidian_search_vault	Pesquisar conteúdo, nomes de arquivo ou tags com paginação limitada por cursor.
obsidian_add_tags	Adicionar tags a uma ou mais notas atomicamente.
obsidian_remove_tags	Remover tags exatas, aninhadas ou selecionadas por curinga atomicamente.
obsidian_rename_tag	Renomear uma tag em todo o vault atomicamente.
obsidian_manage_tags	Fluxo de trabalho unificado de adicionar/remover tags usando a mesma implementação.

Todos os esquemas são contratos estritos de JSON Schema 2020-12 gerados a partir do Zod. Resultados de mutação incluem um ID de transação; falhas de ferramenta retornam isError: true com um código de erro acionável.

Leitura e concorrência

obsidian_read_note retorna um etag. Passe-o como if_match para editar, mover ou excluir quando evitar atualizações perdidas for importante. Operações de tags em lote aceitam um mapa expected_etags. Uma nota alterada retorna REVISION_CONFLICT em vez de ser sobrescrita.

Notas grandes são paginadas usando um cursor opaco vinculado ao caminho e a etag. A pesquisa usa um cursor opaco vinculado à consulta e às opções. As respostas de texto das ferramentas são limitadas a 25.000 caracteres.

Exclusão e recuperação

A lixeira é o padrão. Os bytes e metadados de notas excluídas são armazenados separadamente em .obsidian-mcp/trash; os metadados nunca são injetados na nota. A exclusão permanente exige que confirm_path corresponda exatamente ao caminho relativo canônico.

Transações e snapshots de recuperação ficam em .obsidian-mcp/transactions. Os dados concluídos são retidos por 30 dias e podados do mais antigo para o mais novo acima de 1 GiB por padrão:

obsidian-mcp serve --vault work=/path \
  --recovery-days 14 \
  --recovery-max-bytes 536870912

Inspecione ou restaure uma transação concluída enquanto o servidor MCP está parado:

obsidian-mcp recovery list --vault work=/path
obsidian-mcp recovery restore --vault work=/path --id <transaction-id>

A recuperação se recusa a sobrescrever conteúdo alterado desde a transação selecionada. Snapshots de exclusão permanente são purgados após o commit e não podem ser restaurados.

Segurança de caminho e sistema de arquivos

O servidor:

• canonicaliza as raízes de vault configuradas e rejeita raízes duplicadas ou aninhadas;
• rejeita caminhos de ferramenta absolutos, UNC, unidade do Windows, NUL, barra invertida, vazios e com segmentos de ponto;
• reserva .obsidian, .obsidian-mcp, .git, .backup e .trash do acesso das ferramentas;
• verifica alvos existentes e o ancestral existente mais próximo para novos alvos;
• rejeita symlinks, junctions e caminhos de reparse point, e os ignora durante varreduras;
• não executa shell para validação do sistema de arquivos;
• decodifica estritamente UTF-8 e não substitui silenciosamente bytes inválidos.

O processo precisa de acesso de leitura e escrita a cada vault configurado. obsidian-mcp doctor --vault id=/path valida a prontidão de inicialização e o estado de recuperação.

Comportamento de links e tags

Movimentos reconhecem Wikilinks do Obsidian, embeds, links Markdown, aliases, destinos codificados em URL, cabeçalhos e âncoras de bloco. Um link é reescrito apenas quando resolve inequivocamente para a nota de origem; links ambíguos são relatados e deixados inalterados. A exclusão preserva backlinks, a menos que backlink_action: "mark_broken" seja solicitado.

As tags seguem as regras de insensibilidade a maiúsculas/minúsculas do Obsidian e suportam Unicode, emoji, _, -, / e tags aninhadas. Tags de frontmatter são escritas como listas YAML. O processamento de tags inline ignora código em blocos/inline e comentários HTML. Curingas usam um correspondente limitado em vez de expressões regulares.

Desenvolvimento

npm ci
npm run typecheck
npm test
npm run build
npm run ci

Cada ferramenta possui uma definição tipada em src/tools/<tool>/index.ts; o pequeno registro em src/tools/index.ts aplica o comportamento compartilhado de registro e resposta MCP. O comportamento de sistema de arquivos, transação, Markdown, links e pesquisa vive em utilitários reutilizáveis. Uma nova ferramenta deve usar VaultFs para cada caminho, TransactionManager para mutações, esquemas estritos de entrada/saída, resultados estruturados, anotações e testes de segurança/integração.

Consulte MIGRATING.md para a migração 1.x e SECURITY.md para relatar vulnerabilidades.

Erros de inicialização e avisos de compatibilidade são escritos apenas no stderr com um código estável, o problema detectado, uma correção exata, uma etapa de verificação e um link para a seção de migração correspondente. Se o servidor não aparecer, encontre o código nos logs do cliente MCP e use a referência de diagnóstico.

Licença

MIT