obsidian-mcp

Servidor MCP que expõe um vault do Obsidian (busca, leitura, criação e atualização de notas) via Streamable HTTP.

Status

config.py, auth.py, sync.py, server.py, vault.py e tools.py estão implementados e funcionais.

Related MCP server: Obsidian CLI MCP Server

Tools disponíveis

O servidor expõe 5 tools MCP (src/tools.py, registradas em src/server.py):

• search_notes(query, tag=None, limit=10) — busca por conteúdo, título e tags.

• read_note(path) — lê uma nota e devolve conteúdo + frontmatter.

• list_notes(folder=None, tag=None) — lista notas, opcionalmente filtradas.

• write_note(path, content, frontmatter=None) — cria uma nota nova; não sobrescreve a menos que ALLOW_DESTRUCTIVE=true (erro note_exists / 409 caso contrário).

• replace_section(path, heading, new_content, mode="replace", occurrence=None) — substitui ou anexa (mode="append") o conteúdo de uma seção sem tocar no resto da nota. Se o heading se repetir na nota, a chamada recusa com code: "ambiguous_heading" e informa quantas ocorrências existem — use occurrence (1-based, na ordem do documento) para escolher qual editar. Substituir um heading pai (ex: ## Fase 1) troca a seção inteira, incluindo qualquer subseção aninhada.

Todas retornam {"error": ..., "code": ...} em vez de lançar exceção — ver tools.py para o mapeamento completo de códigos de erro (unsafe_path_error, note_not_found, note_exists, heading_not_found, ambiguous_heading, sync_conflict, invalid_content, internal_error).

Write tools (write_note, replace_section) fazem sync_pull() antes de editar e sync_write() (commit + push) depois, mantendo o repo git do vault sincronizado.

Setup local

uv sync
cp .env.example .env
# editar .env: VAULT_PATH deve apontar para a subpasta do vault dentro do clone
# (ex: .../SecondBrain/SecondBrain), MCP_AUTH_TOKEN para um token forte,
# e ALLOWED_HOST para o host que vai servir o Streamable HTTP.
uv run uvicorn src.server:app --reload

Rodar os testes:

uv run pytest

Testar com o MCP Inspector antes de expor remotamente:

npx @modelcontextprotocol/inspector uv run python -m src.server

Variáveis de ambiente

Definidas em src/config.py (Settings), carregadas de .env. Ver .env.example para os comentários completos.

Deploy (EasyPanel)

Build via Dockerfile, expor por trás do Traefik com TLS. O container precisa de uma deploy key SSH com permissão de push no repo do vault.

Conectar no Claude Code

claude mcp add --transport http obsidian https://SEU-DOMINIO/mcp \
  --header "Authorization: Bearer SEU_TOKEN"

Depois, /mcp dentro do Claude Code lista as tools disponíveis.