🔗 OBSIDIAN MCP SERVER

Bridge MCP usando stdio transport para conectar Claude Desktop ao seu vault Obsidian via Local REST API.

Versão 2.0 - Refatorado para usar arquitetura stdio (sem necessidade de ngrok!)

---

📋 PRÉ-REQUISITOS

✅ Node.js instalado (v18+) ✅ Plugin "Local REST API" ativo no Obsidian ✅ Claude Desktop instalado (para uso local)

NÃO é necessário: ❌ ngrok ou ferramentas de tunneling ❌ Servidor HTTP externo ❌ Configurações de porta ou firewall complexas

---

⚡ INSTALAÇÃO RÁPIDA

1. CLONE OU BAIXE OS ARQUIVOS

git clone <repo-url> obsidian-mcp
cd obsidian-mcp

Ou baixe os arquivos:

obsidian-mcp-server.js
package.json
.env.example

2. INSTALE DEPENDÊNCIAS

npm install

3. CONFIGURE A API KEY

Copie o arquivo de exemplo: ``bash cp .env.example .env ``

Edite .env e preencha: ``bash OBSIDIAN_API_KEY=sua_api_key_aqui OBSIDIAN_URL=http://127.0.0.1:27123 ``

Como obter a API Key:

Abra Obsidian
Settings → Community Plugins → Local REST API
Ative "Enable Non-encrypted (HTTP) Server"
Copie a API Key exibida

4. TESTE O SERVIDOR (Opcional)

./start-server.sh

Você deve ver: ``` ╔════════════════════════════════════════════╗ ║ OBSIDIAN MCP SERVER - RODANDO ✓ ║ ╚════════════════════════════════════════════╝

📁 Obsidian API: http://127.0.0.1:27123 🔑 API Key: 2c134def4a...

🚀 Aguardando comandos do Claude Desktop via stdio... ```

Pressione Ctrl+C para parar.

5. CONFIGURE NO CLAUDE DESKTOP

Veja o guia completo: CLAUDE_DESKTOP_CONFIG.md

Resumo:

Edite claude_desktop_config.json (veja seção abaixo)
Reinicie Claude Desktop
Teste usando ferramentas MCP

---

🖥️ CONFIGURAÇÃO CLAUDE DESKTOP

Localização do Arquivo de Configuração

Windows: `` %APPDATA%\Claude\claude_desktop_config.json ``

macOS: `` ~/Library/Application Support/Claude/claude_desktop_config.json ``

Ou acesse via Claude Desktop: Settings → Developer → "Edit Config"

Exemplo de Configuração

Linux/macOS:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/home/usuario/obsidian-mcp/obsidian-mcp-server.js"],
      "env": {
        "OBSIDIAN_API_KEY": "sua_api_key_aqui",
        "OBSIDIAN_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

Windows (WSL):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "\\\\wsl$\\Ubuntu\\home\\usuario\\obsidian-mcp\\obsidian-mcp-server.js"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "sua_api_key_aqui",
        "OBSIDIAN_URL": "http://172.x.x.x:27123"
      }
    }
  }
}

⚠️ Windows WSL: Ajuste o IP 172.x.x.x para o IP do seu Windows host. Veja instruções completas em CLAUDE_DESKTOP_CONFIG.md.

Reiniciar Claude Desktop

Após editar a configuração:

Feche completamente Claude Desktop
Reabra Claude Desktop
Aguarde alguns segundos para o servidor MCP iniciar

---

🛠️ FERRAMENTAS DISPONÍVEIS

Quando conectado, Claude Desktop terá acesso a:

`list_vault_files()`

Lista todos os arquivos .md do vault `` Claude: "Liste todos os meus arquivos do Obsidian" ``

`read_note(path)`

Lê conteúdo de nota específica `` Claude: "Leia a nota 'Projetos/Ideia X.md'" ``

`search_notes(query)`

Busca por texto em todas as notas `` Claude: "Busque notas sobre 'machine learning'" ``

`create_note(path, content)`

Cria nova nota `` Claude: "Crie uma nota em 'Daily/2025-10-05.md' com resumo da conversa" ``

`update_note(path, content)`

Atualiza nota existente `` Claude: "Atualize 'TODO.md' adicionando tarefa X" ``

---

🔧 CONFIGURAÇÃO AVANÇADA

Mudar URL do Obsidian

Se o Obsidian estiver em outra máquina ou porta:

export OBSIDIAN_URL="http://192.168.1.100:27123"

Ou edite diretamente no .env.

Testar Conexão com Obsidian

curl -s http://127.0.0.1:27123 \
  -H "Authorization: Bearer SUA_API_KEY" | jq

Deve retornar JSON com "status": "OK".

Logs e Debugging

Logs do servidor vão para stderr (não interfere com stdio):

Quando executado pelo Claude Desktop, logs ficam em:
Windows: %APPDATA%\Claude\logs\mcp*.log
macOS: ~/Library/Logs/Claude/mcp*.log

---

🌐 CONFIGURAÇÃO WINDOWS WSL

Se você usa WSL (Windows Subsystem for Linux), use Mirrored Networking Mode para acesso direto ao localhost do Windows.

1. Ativar Mirrored Networking (Windows 11 22H2+)

Crie o arquivo .wslconfig no Windows:

Caminho: C:\Users\SeuUsuario\.wslconfig

Conteúdo: ``ini [wsl2] networkingMode=mirrored ``

2. Reiniciar WSL

wsl --shutdown

Depois reabra o WSL.

3. Configurar .env

Com mirrored networking, use localhost diretamente:

OBSIDIAN_API_KEY=sua_api_key_aqui
OBSIDIAN_URL=http://127.0.0.1:27123

4. Testar Conexão

curl -s http://127.0.0.1:27123 \
  -H "Authorization: Bearer SUA_API_KEY" | jq

Deve retornar JSON com "status": "OK".

Veja guia completo em: CLAUDE_DESKTOP_CONFIG.md

---

❗ TROUBLESHOOTING

"OBSIDIAN_API_KEY não configurada"

→ Configure a variável de ambiente ou edite .env

"ECONNREFUSED 127.0.0.1:27123"

→ Certifique-se que o Obsidian está aberto e o plugin Local REST API está ativo com HTTP server habilitado

"401 Unauthorized"

→ Verifique se a API Key está correta. Copie novamente do Obsidian.

"Server Disconnected" no Claude Desktop

→ Verifique logs em %APPDATA%\Claude\logs\mcp*.log (Windows) ou ~/Library/Logs/Claude/ (macOS)

WSL: Connection refused ao acessar Windows

→ Verifique port proxy e firewall (veja seção Windows WSL acima)

---

🎯 EXEMPLO DE USO REAL

VOCÊ NO CLAUDE DESKTOP: > "Liste todos os meus projetos no Obsidian e resuma os principais tópicos"

CLAUDE FAZ:

Chama list_vault_files()
Filtra arquivos da pasta "Projetos/"
Para cada arquivo, chama read_note(path)
Analisa conteúdo e gera resumo estruturado

VOCÊ: > "Crie uma nota de reunião com as decisões que discutimos"

CLAUDE FAZ:

Chama create_note("Reuniões/2025-10-05.md", conteudo)
Formata a nota em markdown
Confirma criação

---

📦 RODAR COMO SERVIÇO (Opcional)

Linux (systemd)

Crie /etc/systemd/system/obsidian-mcp.service: ```ini [Unit] Description=Obsidian MCP Server After=network.target

[Service] Type=simple User=seu-usuario WorkingDirectory=/caminho/para/obsidian-mcp Environment="OBSIDIAN_API_KEY=sua-key-aqui" Environment="OBSIDIAN_URL=http://127.0.0.1:27123" ExecStart=/usr/bin/node /caminho/para/obsidian-mcp/obsidian-mcp-server.js Restart=always

[Install] WantedBy=multi-user.target ```

sudo systemctl enable obsidian-mcp
sudo systemctl start obsidian-mcp

macOS (launchd)

Crie ~/Library/LaunchAgents/com.obsidian-mcp.plist: ``xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.obsidian-mcp</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/node</string> <string>/caminho/para/obsidian-mcp-server.js</string> </array> <key>EnvironmentVariables</key> <dict> <key>OBSIDIAN_API_KEY</key> <string>sua-key-aqui</string> <key>OBSIDIAN_URL</key> <string>http://127.0.0.1:27123</string> </dict> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> </dict> </plist> ``

launchctl load ~/Library/LaunchAgents/com.obsidian-mcp.plist

⚠️ NOTA: Para uso com Claude Desktop, NÃO é necessário rodar como serviço. Claude Desktop gerencia o processo automaticamente.

---

🔄 MIGRAÇÃO DA VERSÃO 1.0 (HTTP)

Se você usava a versão antiga com ngrok:

O que mudou (v1.0 → v2.0):

✅ Removido servidor HTTP (porta 3000)
✅ Removido necessidade de ngrok
✅ Adicionado stdio transport
✅ Integração direta com Claude Desktop
✅ Corrigido Content-Type para text/markdown (criar/atualizar notas)
✅ Suporte a WSL mirrored networking mode

Como migrar:

Atualize os arquivos do projeto
Execute npm install para instalar @modelcontextprotocol/sdk
Configure Claude Desktop seguindo CLAUDE_DESKTOP_CONFIG.md
Remova referências a ngrok

Backup da versão HTTP: O arquivo original foi salvo em obsidian-mcp-server-http.js.bak

---

📚 ARQUITETURA

┌─────────────────┐
│ Claude Desktop  │
│   (Windows)     │
└────────┬────────┘
         │ stdio transport
         │ (stdin/stdout)
         ▼
┌─────────────────┐
│  MCP Server     │
│     (WSL)       │
└────────┬────────┘
         │ HTTP REST API
         │ (via port proxy)
         ▼
┌─────────────────┐
│ Obsidian REST   │
│ API (Windows)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Obsidian       │
│  Vault (.md)    │
└─────────────────┘

---

📝 NOTAS TÉCNICAS

Content-Type para Criação de Notas

O Obsidian Local REST API requer Content-Type: text/markdown para operações de criação e atualização de arquivos. O servidor MCP implementa dois métodos de requisição:

request() - Para operações de leitura/listagem (usa application/json)
requestText() - Para criar/atualizar arquivos (usa text/markdown)

Se você encontrar erro 40010 ao criar notas, verifique se está usando a versão v2.0+ do servidor que inclui essa correção.

WSL Mirrored Networking

Para Windows 11 22H2+, o modo mirrored networking permite que WSL acesse localhost do Windows diretamente, eliminando necessidade de:

Port proxy (netsh)
Descobrir IP do host Windows
Configurar firewall

Simplesmente crie .wslconfig com networkingMode=mirrored e reinicie WSL.

---

🚀 PRÓXIMOS PASSOS

Depois de configurar:

"Liste todos os meus arquivos do Obsidian"
"Analise os temas mais frequentes nas minhas notas"
"Encontre todas as referências sobre [tópico X]"
"Crie uma nota resumindo nossas conversas de hoje"
"Organize minhas notas de projeto criando um índice"

---

🤝 CONTRIBUINDO

Melhorias são bem-vindas! Sinta-se livre para:

Reportar bugs
Sugerir novas funcionalidades
Enviar pull requests

---

📄 LICENÇA

MIT - Use como quiser!

---

📖 RECURSOS ADICIONAIS

CLAUDE_DESKTOP_CONFIG.md - Guia completo de configuração
Model Context Protocol - Documentação oficial MCP
Obsidian Local REST API - Plugin Obsidian
Claude Desktop - Download Claude Desktop

---

🎖️ CRÉDITOS

Desenvolvido por Aurora × Fernando 🤝

MCP (Model Context Protocol) por Anthropic Obsidian Local REST API por Adam Coddington

---

Versão 2.0.0 - Refatorado para stdio transport (2025)

obsidian-mcp-server