Instalação — obsidian-mcp-secure

✅ Pré-requisitos

Item	Versão / detalhe
Obsidian Desktop	qualquer versão recente (≥ 1.6)
Plugin Local REST API	instalado e habilitado
Node.js	18 ou superior
Claude Desktop	qualquer versão recente

1️⃣ Instalar e configurar o plugin Local REST API

1. Abre o Obsidian com o vault que vai ser exposto
2. Settings → Community plugins → Browse
3. Busca Local REST API (autor: Adam Coddington)
4. Clica Install → Enable
5. Volta em Settings → Community plugins → Local REST API:
   • ✅ Enable Non-encrypted (HTTP) Server (mais simples que HTTPS self-signed)
   • Non-encrypted Server Port: mantém em 27123
   • Copia a API Key mostrada no topo da página

Mantém o Obsidian aberto

O plugin só responde quando o app está rodando. Não tem como o MCP funcionar com Obsidian fechado.

2️⃣ Localizar o claude_desktop_config.json

OS	Caminho
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Se o arquivo não existir, cria — ele é só um JSON.

Atalho via Claude Desktop

File → Settings → Developer → Local MCP servers → Edit Config abre o arquivo no editor padrão sem precisar lembrar do caminho.

3️⃣ Adicionar o bloco do obsidian-secure

Windows

{
  "mcpServers": {
    "obsidian-secure": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-secure"],
      "env": {
        "OBSIDIAN_API_KEY": "sua-api-key-do-plugin",
        "OBSIDIAN_HOST": "http://127.0.0.1",
        "OBSIDIAN_PORT": "27123",
        "LOG_DIR": "C:/Users/seu-user/obsidian-mcp-logs"
      }
    }
  }
}

Se npx falhar silenciosamente

Algumas versões do Claude Desktop não resolvem npx puro no PATH em Windows. Troca pra "command": "npx.cmd".

macOS

{
  "mcpServers": {
    "obsidian-secure": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-secure"],
      "env": {
        "OBSIDIAN_API_KEY": "sua-api-key-do-plugin",
        "OBSIDIAN_HOST": "http://127.0.0.1",
        "OBSIDIAN_PORT": "27123",
        "LOG_DIR": "/Users/seu-user/obsidian-mcp-logs"
      }
    }
  }
}

Linux

{
  "mcpServers": {
    "obsidian-secure": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-secure"],
      "env": {
        "OBSIDIAN_API_KEY": "sua-api-key-do-plugin",
        "OBSIDIAN_HOST": "http://127.0.0.1",
        "OBSIDIAN_PORT": "27123",
        "LOG_DIR": "/home/seu-user/obsidian-mcp-logs"
      }
    }
  }
}

4️⃣ Reiniciar o Claude Desktop

Quit completo, não só fechar a janela

Windows / Linux: ícone na tray → Quit ClaudemacOS: Cmd+Q (não fechar com o X)

Depois reabrir.

5️⃣ Validar

Na conversa do Claude Desktop:

Use a tool list_notes do obsidian-secure pra listar minhas notas.

Resultado esperado: lista dos arquivos .md do seu vault.

🐛 Troubleshooting

"Server disconnected" no menu de MCP

Verifica os logs do Claude Desktop:

OS	Caminho
Windows	%APPDATA%\Claude\logs\mcp-server-obsidian-secure.log
macOS	~/Library/Logs/Claude/mcp-server-obsidian-secure.log

Causas comuns:

• npm not found → npx.cmd (Windows) ou Node.js fora do PATH
• EACCES no LOG_DIR → pasta não existe ou sem permissão de escrita
• Claude Desktop não detectou a config → confere syntax do JSON

Erro 401 ao chamar tools

API key errada no config. Volta no plugin Local REST API → copia novamente a key e atualiza no claude_desktop_config.json. Reinicia Claude Desktop.

Erro ECONNREFUSED

• Obsidian fechado → reabre
• Plugin Local REST API desabilitado → habilita
• "Enable Non-encrypted HTTP Server" desmarcado no plugin → marca

Erro de timeout

Vault muito grande pode estourar timeout. Configura OBSIDIAN_TIMEOUT_MS=30000 (30s) na env.

🔁 Atualização

# Limpa cache do npx pra forçar nova versão
npx clear-npx-cache
# Reinicia Claude Desktop — npx vai pegar a versão mais recente automaticamente

Pra fixar uma versão específica, troca "args": ["-y", "obsidian-mcp-secure"] por "args": ["-y", "obsidian-mcp-secure@1.0.4"].

📋 Checklist final

• [ ] Plugin Local REST API instalado e habilitado
• [ ] HTTP Server marcado, porta 27123
• [ ] API key copiada
• [ ] claude_desktop_config.json editado com bloco correto
• [ ] LOG_DIR aponta pra pasta com permissão de escrita
• [ ] Claude Desktop reiniciado (Quit completo)
• [ ] Teste com list_notes retorna arquivos