obsidian-mcp

MCP server para Obsidian vaults — gerenciador multi-brain com templates, registry persistente, busca, CRUD, frontmatter, wikilinks e context bundling.

Funciona com Hermes Agent e Claude Code simultaneamente, compartilhando os mesmos vaults via registry cross-tool.

Features

• Multi-brain — crie, remova e gerencie múltiplos vaults (cérebros) sem restart
• Registry persistente — ~/.obsidian-mcp/vault-registry.json como fonte da verdade cross-tool
• 4 templates — roteirista, genérico, pesquisa, minimal
• 22 tools MCP — lifecycle de vaults, CRUD de notas, busca, backlinks, context bundle
• Frontmatter-aware — parse, serialize, update de YAML frontmatter
• Wikilinks — extração, resolução, backlinks automáticos
• Installer cross-tool — configura Hermes + Claude Code com um comando
• 124 testes — cobertura completa (pytest)

Instalação Rápida

# Clone o projeto
git clone https://github.com/SEU_USUARIO/obsidian-mcp.git
cd obsidian-mcp

# Instale o MCP server (Hermes + Claude Code)
uv run install.py

# Instale as skills do agente
uv run scripts/install-skills.py

# Verifique
uv run install.py --status
uv run scripts/install-skills.py --status

Reinicie o Hermes e/ou Claude Code após a instalação.

Requisitos

• Python 3.10+
• uv
• Hermes Agent e/ou Claude Code

Tools MCP (22)

Vault Lifecycle

Tool	Descrição
create_vault	Cria um novo cérebro a partir de um template
remove_vault	Remove (arquiva por padrão) ou deleta um cérebro
vault_status	Status de um ou todos os cérebros
list_vault_templates	Lista templates disponíveis

Vault Info

Tool	Descrição
list_vaults	Lista cérebros registrados
vault_overview	Visão estrutural (pastas, tags, recentes)
vault_briefing	Briefing legível para início de sessão

Notas — CRUD

Tool	Descrição
read_note	Lê uma nota por nome
create_note	Cria nota (com template opcional)
update_frontmatter	Atualiza campos YAML sem tocar no body
append_to_note	Adiciona conteúdo ao final da nota

Notas — Busca

Tool	Descrição
search_notes	Busca textual com filtros (tags, folder, status)
context_bundle	Gather completo sobre um tema (busca + wikilinks)
get_backlinks	Notas que linkam para a nota dada

Notas — Listagem

Tool	Descrição
list_by_tag	Filtra notas por tag
list_by_stage	Filtra notas por etapa/status

Infra

Tool	Descrição
refresh_index	Re-scan do vault (após mudanças externas)

Templates de Vault

Template	Pastas	Uso
roteirista	11	Roteiros, blog, conteúdo (estilo Ensinamentos da Vida)
generico	6	Conhecimento pessoal (método PARA)
pesquisa	5	Pesquisa acadêmica / investigação
minimal	0	Vault livre (só HOME.md)

Arquitetura

~/.obsidian-mcp/vault-registry.json   ← registry cross-tool (fonte da verdade)

src/obsidian_mcp/
├── server.py       ← FastMCP server + 22 tools
├── vault.py        ← VaultIndex (scan/search/CRUD) + VaultManager (lifecycle)
├── registry.py     ← VaultRegistry (JSON persistente)
├── templates.py    ← 4 templates de vault
├── frontmatter.py  ← YAML frontmatter parse/serialize/update
├── links.py        ← wikilink extraction, resolution, backlinks
└── models.py       ← Note, SearchResult, VaultOverview

skills/
├── obsidian-mcp/           ← skill MESTRE (dossiê do agente)
└── obsidian-mcp-install/   ← skill de instalação guiada

scripts/
└── install-skills.py       ← instalador de skills (Hermes + Claude Code)

install.py                  ← instalador do MCP server (Hermes + Claude Code)

Fluxo de dados

Registry JSON → VaultManager carrega vaults → VaultIndex indexa notas
create_vault / remove_vault → atualizam registry + memória (hot-reload)
Hermes e Claude Code → leem do MESMO registry → mesmos cérebros

Startup do server

Prioridade: registry → env vars (seed) → auto-discovery (seed)

Configuração

Hermes Agent

~/.hermes/config.yaml:

mcp_servers:
  obsidian:
    command: uv
    args:
      - run
      - --project
      - C:/Users/fernando/Downloads/obsidian-mcp
      - obsidian-mcp

⚠️ args DEVE ser lista YAML, nunca string JSON.

Claude Code

~/.claude/settings.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--project", "C:/Users/fernando/Downloads/obsidian-mcp", "obsidian-mcp"]
    }
  }
}

Installer

uv run install.py              # configura Hermes + Claude Code
uv run install.py --hermes     # só Hermes
uv run install.py --claude     # só Claude Code
uv run install.py --status     # mostra status
uv run install.py --remove     # remove config

Skills do Agente

obsidian-mcp (skill MESTRE)

Dossiê completo: 22 tools com exemplos, gatilhos → ações, comportamento do agente, convenções de conteúdo, segurança, pitfalls. O agente carrega essa skill pra operar o sistema sem "viajar na maionese".

obsidian-mcp-install

Guia de instalação passo a passo para usuários leigos. Pré-requisitos, instalação automática/manual, troubleshooting, desinstalação.

Instalar skills

uv run scripts/install-skills.py              # instala em ambos
uv run scripts/install-skills.py --hermes     # só Hermes
uv run scripts/install-skills.py --claude     # só Claude Code
uv run scripts/install-skills.py --status     # mostra status

Desenvolvimento

cd obsidian-mcp

# Testes (124, ~2s)
uv run pytest -v

# Inspect server
OBSIDIAN_VAULT_PATH="C:/path/to/vault" uv run fastmcp inspect mcp_server.py:mcp

# Testar vault via Python
uv run python -c "
from obsidian_mcp.vault import VaultIndex
vi = VaultIndex('C:/path/to/vault')
print(vi.briefing())
"

Pitfalls Conhecidos

1. YAML args — hermes config set escreve args como string JSON. Precisa ser lista YAML.
2. Index stale — mudanças via terminal/Obsidian app não atualizam o index. Chame refresh_index.
3. Sem delete_note — não existe tool de deletar nota. Use rm + refresh_index.
4. fastmcp call — não herda env vars do shell. Teste via Python direto.
5. fastmcp inspect — use mcp_server.py wrapper (relative imports quebram direto).

Licença

MIT