🔗 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:

cp .env.example .env

Edite .env e preencha:

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

Como obter a API Key:

1. Abra Obsidian
2. Settings → Community Plugins → Local REST API
3. Ative "Enable Non-encrypted (HTTP) Server"
4. 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:

1. Edite claude_desktop_config.json (veja seção abaixo)
2. Reinicie Claude Desktop
3. 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:

1. Feche completamente Claude Desktop
2. Reabra Claude Desktop
3. 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:

[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:

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

VOCÊ:

"Crie uma nota de reunião com as decisões que discutimos"

CLAUDE FAZ:

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

---

📦 RODAR COMO SERVIÇO (Opcional)

Linux (systemd)

Crie /etc/systemd/system/obsidian-mcp.service:

[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 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:

1. Atualize os arquivos do projeto
2. Execute npm install para instalar @modelcontextprotocol/sdk
3. Configure Claude Desktop seguindo CLAUDE_DESKTOP_CONFIG.md
4. 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:

1. "Liste todos os meus arquivos do Obsidian"
2. "Analise os temas mais frequentes nas minhas notas"
3. "Encontre todas as referências sobre [tópico X]"
4. "Crie uma nota resumindo nossas conversas de hoje"
5. "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)