vault-mcp-server

MCP server genérico pra consultar e alimentar um vault Obsidian (ou qualquer pasta de arquivos .md). Não sabe nada sobre a estrutura de nenhum vault específico — isso é responsabilidade do AGENTS.md/convenções de cada vault, lido pelo agente que usa as tools, não codificado aqui.

Ferramentas

Módulo	Ferramenta	Descrição
Busca	search_notes(query, subfolder=None, max_results=None)	Busca texto (regex, cai pra literal se inválido) em .md, opcionalmente só numa subpasta
Busca	search_by_tag(tag, subfolder=None)	Busca notas com a tag no frontmatter (tags:) ou inline (#tag)
Busca	get_backlinks(path)	Notas que linkam pra essa via [[wikilink]]
Leitura	read_note(path)	Conteúdo bruto de uma nota (frontmatter incluso)
Leitura	list_notes(subfolder=None)	Lista recursiva de .md com frontmatter de preview
Leitura	list_folders(subfolder=None)	Subpastas de um nível
Leitura	get_note_metadata(path)	Só o frontmatter parseado
Escrita	write_note(path, content, mode="append")	Cria (mode="create", falha se já existir) ou concatena (mode="append", cria se não existir)
Escrita	rename_note(path, new_filename)	Renomeia, mesma pasta
Escrita	move_note(path, new_path)	Move/renomeia pra qualquer caminho no vault
Escrita	delete_note(path)	Soft delete — move pra .trash/, não apaga de verdade

Limitação conhecida: rename_note/move_note não reescrevem [[wikilinks]] que outras notas tenham pra elas (diferente do Obsidian, que faz isso automaticamente pela UI). Rode get_backlinks antes de renomear pra saber o que pode quebrar.

write_note não faz git. Só grava o arquivo — commit/push continua manual (mesmo fluxo que o AGENTS.md de cada vault já deve documentar pra agentes com acesso a shell).

Variáveis de ambiente

Variável	Default	Faz
VAULT_MCP_ROOT	~/vault	Raiz do vault a servir — trocar aponta pra qualquer outro vault
VAULT_MCP_SEARCH_MAX_RESULTS	50	Limite de resultados de busca (1-500)
VAULT_MCP_SEARCH_CONTEXT_CHARS	120	Tamanho do trecho retornado por match (20-1000)
VAULT_MCP_WRITE_MAX_CHARS	20000	Limite de tamanho de conteúdo em write_note (1-200000)
VAULT_MCP_BLOCKED_FOLDERS	(vazio)	CSV de pastas de topo extras a bloquear pra leitura/escrita, além de .git/.obsidian/.trash (sempre bloqueados)

Segurança

Todo caminho é resolvido e validado contra escapar da raiz do vault (sem .., sem caminho absoluto fora do vault). Só arquivos .md são lidos/escritos. Pastas de topo em VAULT_MCP_BLOCKED_FOLDERS (+ as três padrão) ficam fora tanto de leitura quanto de escrita.

Registro

Pra este vault específico (~/vault), bloqueando também _scripts/ (é tooling, não notas):

claude mcp add --scope user vault \
  --env VAULT_MCP_ROOT=$HOME/vault \
  --env VAULT_MCP_BLOCKED_FOLDERS=_scripts \
  -- uv run --directory ~/dev/pessoal/vault-mcp-server server.py

--scope user deixa disponível em qualquer sessão do Claude Code, em qualquer repo — não só quando se está dentro do vault. O mesmo binário serve qualquer outro vault só trocando VAULT_MCP_ROOT.

Codex CLI ainda não está instalado nesta máquina; quando estiver, o mesmo servidor se registra via entrada mcp_servers no config.toml do Codex, apontando pro mesmo comando (uv run --directory ... server.py) com as mesmas env vars.