obsidian-brain

obsidian-brain

Um servidor MCP Node autônomo que dá ao Claude (e a qualquer outro cliente MCP) busca semântica + grafo de conhecimento + edição de vault sobre um vault do Obsidian. Executa como um único processo local stdio — sem plugin, sem ponte HTTP, sem chave de API, nada hospedado. O conteúdo do seu vault nunca sai da sua máquina.

📖 Documentação completa → sweir1.github.io/obsidian-brain Plugin complementar → sweir1/obsidian-brain-plugin (opcional — desbloqueia active_note, dataview_query, base_query)

Conteúdo — Por quê · Início rápido · O que você obtém · Como funciona · Plugin complementar · Solução de problemas · Versões recentes

Por que obsidian-brain?

• Funciona sem o Obsidian aberto — ao contrário de servidores baseados em API REST Local, o obsidian-brain lê arquivos .md diretamente do disco. O Obsidian pode estar fechado; seu vault é apenas uma pasta.
• Não requer o plugin Local REST API — nada para instalar dentro do Obsidian para a experiência principal.
• Busca semântica em nível de bloco com recuperação híbrida RRF — embeddings na granularidade de cabeçalhos Markdown, combinados com FTS5 BM25 via Reciprocal Rank Fusion. Encontra o bloco exato, classifica pelo significado.
• O único servidor MCP do Obsidian com PageRank + Louvain + análise de grafos — pergunte pelas notas mais influentes do seu vault, notas de ponte, clusters temáticos. Ninguém mais oferece isso.
• Provedor Ollama para embeddings locais de alta qualidade — alterne para qwen3-embedding:0.6b, nomic-embed-text, bge-m3, etc. com uma variável de ambiente.
• Tudo em uma instalação npx — sem clone, sem build, sem chave de API, sem endpoint hospedado. O conteúdo do vault nunca sai da sua máquina.

Início rápido

Instalação em uma linha (macOS + Claude Desktop)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sweir1/obsidian-brain/main/scripts/install.sh)"

Instala Homebrew + Node 20+ se você ainda não os tiver, adiciona os symlinks /usr/local/bin que o Claude Desktop precisa, mescla o obsidian-brain no seu claude_desktop_config.json, abre o painel de Full Disk Access para você ativar o Claude e reinicia o Claude. Será solicitada sua senha do macOS uma vez (para Homebrew + symlinks) e o caminho do seu vault uma vez. Todo o resto é automático. Audite o que ele faz: scripts/install.sh.

Instalação manual

Requer Node 20+ e um vault do Obsidian (ou qualquer pasta de arquivos .md — o próprio Obsidian é opcional).

Conecte o obsidian-brain ao seu cliente MCP. Exemplo para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": ["-y", "obsidian-brain@latest", "server"],
      "env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
    }
  }
}

Saia do Claude Desktop (⌘Q no macOS) e reinicie. É isso.

[!NOTE] Na primeira inicialização, o servidor indexa automaticamente seu vault e baixa um modelo de embeddings de ~34 MB. As ferramentas podem levar de 30 a 60 s para aparecer no cliente. Inicializações subsequentes são instantâneas.

[!TIP] Não é desenvolvedor? O passo a passo para macOS cobre Homebrew, Node, a correção de PATH para apps GUI e Full Disk Access passo a passo.

Para todos os outros clientes MCP (Claude Code, Cursor, VS Code, Jan, Windsurf, Cline, Zed, LM Studio, JetBrains AI, Opencode, Codex CLI, Gemini CLI, Warp): veja Instalar no seu cliente MCP.

→ Referência completa de variáveis de ambiente: Configuração → Detalhes de modelo / preset / Ollama: Modelo de embeddings → Migrando do plugin do aaronsb: Guia de migração

O que você obtém

18 ferramentas MCP agrupadas por intenção:

• Encontrar & ler — search, list_notes, read_note
• Entender o grafo — find_connections, find_path_between, detect_themes, rank_notes
• Escrever — create_note, edit_note, apply_edit_preview, link_notes, move_note, delete_note
• Editor ao vivo (requer plugin complementar) — active_note, dataview_query, base_query
• Manutenção — reindex, index_status

→ Argumentos, exemplos e formatos de resposta: Referência de ferramentas

Como funciona

flowchart LR
    Client["<b>MCP Client</b><br/>Claude Desktop · Claude Code<br/>Cursor · Jan · Windsurf · ..."]

    subgraph OB ["obsidian-brain (Node process)"]
        direction TB
        SQL["<b>SQLite index</b><br/>nodes · edges<br/>FTS5 · vec0 embeddings"]
        Vault["<b>Vault on disk</b><br/>your .md files"]
        Vault -->|"parse + embed"| SQL
        SQL -.->|"writes"| Vault
    end

    Client <-->|"stdio JSON-RPC"| OB

Recuperação e escrita passam por um índice SQLite: leituras são baratas em microssegundos, escritas chegam ao disco imediatamente e reindexam incrementalmente o arquivo afetado. Os embeddings são em nível de bloco (divisor recursivo ciente de cabeçalhos, preservando blocos de código + LaTeX), e o modo hybrid padrão do search combina classificação semântica em nível de bloco com FTS5 BM25 via Reciprocal Rank Fusion.

→ Explicação mais aprofundada — por que stdio, por que SQLite, por que embeddings locais: Arquitetura → Comportamento do observador ao vivo + debounces: Atualizações ao vivo → Reindexação agendada (macOS launchd / Linux systemd): Indexação agendada (macOS) · (Linux)

Plugin complementar (opcional)

Um plugin Obsidian opcional em sweir1/obsidian-brain-plugin expõe o estado de runtime ao vivo do Obsidian — editor ativo, resultados do Dataview, linhas do Bases — por um endpoint HTTP localhost. Quando instalado e o Obsidian está em execução, active_note, dataview_query e base_query são ativados. Instale via BRAT com o ID do repositório sweir1/obsidian-brain-plugin.

Envie o plugin e o servidor na mesma major.minor — servidor v1.7.x emparelha com plugin v1.7.x. Variação de versão de patch é aceitável.

→ Modelo de segurança, handshake de capacidades, cobertura de recursos Dataview / Bases: Plugin complementar

Solução de problemas

Os quatro mais comuns:

• "Connector has no tools available" no Claude Desktop — geralmente o servidor travou na inicialização. Verifique ~/Library/Logs/Claude/mcp-server-obsidian-brain.log. Correção: npm install -g obsidian-brain@latest, saia do Claude (⌘Q), reinicie.
• Incompatibilidade de ERR_DLOPEN_FAILED / NODE_MODULE_VERSION — better-sqlite3 compilado contra um ABI Node diferente. Correção: PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3.
• Vault path not configured — VAULT_PATH não está definido. Defina-o no bloco env da configuração do seu cliente ou no shell.
• Versão antiga carregando via npx (seu cliente ainda mostra a versão anterior após uma publicação) — cache npx obsoleto. Correção: rm -rf ~/.npm/_npx, depois reinicie seu cliente. Manter @latest na sua configuração evita isso.

→ Guia completo de solução de problemas (observador não disparando, índice obsoleto, executando vários clientes, timeouts, incompatibilidade de dimensão de embeddings, locais de logs): docs/troubleshooting.md

Versões recentes

• v1.7.24 (2026-05-16) — callout BYOM em embeddings.md + 5 bumps de devDependencies
• v1.7.23 (2026-05-16) — gate de auto-pull BYOM Ollama + varredura de logger + teste unitário SIGTERM
• v1.7.22 (2026-05-15) — stderr estruturado (NDJSON) + estado de preparação Ollama + bumps de segurança dependabot + teste de integração de drenagem SIGTERM
• v1.7.21 (2026-04-27) — correção do seletor de vault no install.sh + ollama pull automático + polimento de docs/testes
• v1.7.20 (2026-04-27) — bug de busca por prefixo Ollama + 13 itens de polimento de auditoria

→ Changelog completo: docs/CHANGELOG.md · Plano futuro: docs/roadmap.md · Compilar a partir do código-fonte: docs/development.md

Créditos

Agradecimentos a obra/knowledge-graph e aaronsb/obsidian-mcp-plugin pelas ideias e código nos quais este projeto se baseia. Também Xenova/transformers.js (embeddings locais), graphology (análise de grafos) e sqlite-vec (busca vetorial em SQLite).

Projetos relacionados

• apple-notes-brain — servidor MCP irmão para Apple Notes no macOS: ler, escrever e buscar com round-trip completo de Markdown em ambas as direções.

Licença

Apache License 2.0 — Copyright 2026 sweir1.