Obsidian

Um servidor para interagir com seu cofre Obsidian.

GitHub
37
Experimente este MCPPatrocinado

Documentação

Obsidian MCP Server Banner

Servidor de Ferramentas MCP do Obsidian

Security Scan (Trivy + Bandit) Bandit Trivy

Este projeto fornece um servidor Model Context Protocol (MCP) que expõe ferramentas para interagir com um cofre do Obsidian.

Sumário

Recursos

Permite que clientes MCP (como assistentes de IA) possam:

  • Ler e escrever notas
  • Gerenciar metadados de notas (frontmatter)
  • Listar notas e pastas
  • Pesquisar notas por conteúdo ou metadados
  • Gerenciar notas diárias
  • Obter links de saída, backlinks e tags

Instalação

  1. Clone o repositório (se ainda não o fez):

    # git clone <repository-url>
# cd OMCP

  2. Navegue até o diretório do projeto:

    cd /path/to/your/OMCP

  3. Crie um ambiente virtual Python (recomendado para evitar conflitos de dependências):

    python -m venv .venv

  4. Ative o ambiente virtual:

    • No Windows PowerShell: 
      .venv\Scripts\Activate.ps1
    • No Linux/macOS: 
      source .venv/bin/activate

    (Seu prompt de terminal agora deve mostrar (.venv) no início)

  5. Instale o pacote e suas dependências:

    pip install .

Configuração

Este servidor é configurado usando variáveis de ambiente, que podem ser convenientemente gerenciadas usando um arquivo .env na raiz do projeto.

  1. Copie o arquivo de exemplo:

    # From the project root directory (OMCP/)
cp .env.example .env

    (No Windows, você pode usar copy .env.example .env)

  2. Edite o arquivo .env: Abra o arquivo .env recém-criado em um editor de texto.

  3. Defina OMCP_VAULT_PATH: Esta é a única variável obrigatória. Atualize-a com o caminho absoluto para o seu cofre do Obsidian. Use barras normais (/) para caminhos, mesmo no Windows.

    OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"

  4. Revise as Configurações Opcionais: Ajuste as outras variáveis OMCP_ para notas diárias, porta do servidor ou diretório de backup, se necessário. Leia os comentários no arquivo para obter explicações.

(Alternativamente, em vez de usar um arquivo .env, você pode definir essas variáveis como variáveis de ambiente reais do sistema. O servidor priorizará as variáveis de ambiente do sistema sobre o arquivo .env se ambos estiverem definidos.)

Execução Manual (para Testes/Depuração)

Embora aplicativos clientes como o Claude Desktop iniciem o servidor automaticamente usando a configuração descrita abaixo, você também pode executar o servidor manualmente a partir do seu terminal para testes diretos ou depuração.

  1. Garanta que a Configuração Esteja Feita: Certifique-se de ter criado e configurado seu arquivo .env conforme descrito na seção Configuração.
  2. Ative o Ambiente Virtual: 
    # If not already active
.venv\Scripts\Activate.ps1
    (Use source .venv/bin/activate no Linux/macOS)
  3. Execute o script do servidor: 
    (.venv) ...> python obsidian_mcp_server/main.py

O servidor iniciará e imprimirá o endereço em que está escutando (por exemplo, http://127.0.0.1:8001). Você normalmente pressionaria Ctrl+C para interrompê-lo quando terminar os testes.

Lembre-se: Se você pretende usar este servidor com o Claude Desktop ou um lançador similar, você não deve executá-lo manualmente dessa forma. Configure o aplicativo cliente (veja a próxima seção), e ele cuidará de iniciar e parar o processo do servidor.

Configuração do Cliente (Exemplo: Claude Desktop)

Muitos clientes MCP (como o Claude Desktop) podem iniciar processos de servidor diretamente. Para configurar tal cliente, você normalmente precisa editar seu arquivo de configuração JSON (por exemplo, claude_desktop_config.json no macOS/Linux, encontre o caminho equivalente no Windows em AppData).

⚠️ Regras Importantes de Formatação JSON:

  1. Arquivos JSON não suportam comentários (remova quaisquer comentários // ou /* */)
  2. Todas as strings devem ser devidamente citadas com aspas duplas (")
  3. Caminhos do Windows devem usar barras invertidas escapadas (\\)
  4. Use um validador JSON (como jsonlint.com) para verificar sua sintaxe

Aqui está um exemplo de entrada para adicionar sob a chave mcpServers na configuração JSON do cliente:

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"],
      "env": {
        "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault",
        "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily"
      }
    }
  }
}

Pontos-Chave:

  • Substitua os caminhos pelos caminhos absolutos relevantes para o seu sistema
  • Para caminhos do Windows nos campos command e args:
    • Use barras invertidas duplas (\\) para separadores de caminho
    • Inclua a extensão .exe para o executável Python
  • Para caminhos do Windows no bloco env:
    • Use barras normais (/) para melhor compatibilidade
    • Não inclua a extensão .exe
  • O caminho command deve apontar para o executável python.exe dentro do .venv que você criou
  • O caminho args deve apontar para o arquivo main.py dentro da subpasta obsidian_mcp_server
  • Usar o bloco env é a maneira mais confiável de garantir que o servidor encontre o caminho do seu cofre
  • Lembre-se de reiniciar o aplicativo cliente após modificar sua configuração JSON

Armadilhas Comuns a Evitar:

  1. Não use barras invertidas simples em caminhos do Windows
  2. Não inclua comentários no JSON
  3. Não se esqueça de escapar barras invertidas em caminhos do Windows
  4. Não misture barras normais e invertidas no mesmo caminho
  5. Não se esqueça de citar corretamente todas as strings

Ferramentas MCP Disponíveis

  • list_folders
  • list_notes
  • get_note_content
  • get_note_metadata
  • get_outgoing_links
  • get_backlinks
  • get_all_tags
  • search_notes_content
  • search_notes_metadata
  • search_folders
  • create_note
  • edit_note
  • append_to_note
  • update_note_metadata
  • delete_note
  • get_daily_note_path
  • create_daily_note
  • append_to_daily_note

Roteiro

Para um plano de implementação detalhado e faseado, incluindo considerações de tratamento de erros, consulte o arquivo ROADMAP.md.

Este projeto é desenvolvido ativamente. Aqui está uma visão dos recursos planejados:

v1.x (Curto Prazo)

  • Criação de Notas Baseada em Modelos:
    • Configurar um diretório de modelos (OMCP_TEMPLATE_DIR).
    • Implementar a ferramenta create_note_from_template (usando nome do modelo, caminho de destino, metadados opcionais).
    • Adicionar testes para criação de modelos.
  • Criação de Pastas:
    • Implementar a função utilitária create_folder.
    • Implementar a ferramenta MCP create_folder.
    • Adicionar testes para criação de pastas.

v1.y (Médio Prazo / Melhorias Futuras)

  • Substituição de variáveis em modelos (por exemplo, {{DATE}}).
  • Ferramenta list_templates.
  • Ferramentas avançadas de atualização de notas (por exemplo, append_to_note_by_metadata).
  • Ferramenta list_vault_structure para visão abrangente da hierarquia do cofre.
  • Revisão e expansão abrangente de testes.

v2.x+ (Ideias Potenciais / Longo Prazo)

  • Ferramentas de Organização:
    • move_item(source, destination) (A versão inicial pode não atualizar links).
    • rename_item(path, new_name) (A versão inicial pode não atualizar links).
  • Ferramentas de Manipulação de Conteúdo:
    • replace_text_in_note(path, old, new, count).
    • prepend_to_note(path, content).
    • append_to_section(path, heading, content) (Requer análise confiável de cabeçalhos).
  • Ferramentas de Consulta:
    • get_local_graph(path) (Combinar links de saída/backlinks).
    • search_notes_by_metadata_field(key, value).
  • Ferramentas de Integração de Plugins:
    • Integração Dataview:
      • execute_dataview_query(query_type, query) - Executar consultas Dataview e obter resultados estruturados
      • search_by_dataview_field(field, value) - Pesquisar notas por campos Dataview
    • Gerenciamento de Tarefas:
      • query_tasks(status, due_date, tags) - Pesquisar e filtrar tarefas em todo o cofre
    • Integração Kanban:
      • get_kanban_data(board_path) - Obter dados estruturados de quadros kanban
    • Integração de Calendário:
      • get_calendar_events(start_date, end_date) - Consultar eventos e tarefas do calendário

Perguntas Frequentes (FAQ)

Problemas de Configuração

P: Meu servidor não consegue encontrar meu cofre. O que está errado? R: Isso geralmente é devido à configuração incorreta do caminho. Verifique:

  1. O OMCP_VAULT_PATH no seu arquivo .env usa barras normais (/) mesmo no Windows
  2. O caminho é absoluto (começa da raiz)
  3. O caminho não termina com barra final
  4. O diretório do cofre existe e é acessível

P: Por que estou recebendo erros de permissão? R: Isso normalmente acontece quando:

  1. O caminho do cofre aponta para um diretório restrito
  2. O processo Python não tem permissões de leitura/escrita
  3. O cofre está em uma pasta sincronizada na nuvem (como OneDrive) que está sincronizando no momento

Tente:

  1. Mover seu cofre para um diretório local
  2. Executar o servidor com permissões elevadas
  3. Verificar se seu antivírus não está bloqueando o acesso

Problemas de Conexão do Cliente

P: Meu cliente de IA não consegue se conectar ao servidor. O que devo verificar? R: Verifique estes problemas comuns:

  1. O servidor está realmente em execução (verifique a saída do terminal)
  2. A porta na configuração do seu cliente corresponde à porta do servidor
  3. O caminho do Python na configuração do seu cliente aponta para o ambiente virtual correto
  4. Todas as variáveis de ambiente estão devidamente definidas na configuração do cliente

P: Por que recebo erros de "Conexão recusada"? R: Isso geralmente significa:

  1. O servidor não está em execução
  2. A porta já está em uso
  3. O firewall está bloqueando a conexão

Tente:

  1. Verifique se o servidor está em execução: netstat -ano | findstr :8001 (Windows)
  2. Tente uma porta diferente definindo OMCP_SERVER_PORT no seu .env
  3. Desative temporariamente o firewall para testar

P: Recebo "[error] [obsidian_vault] Unexpected token 'S', "Starting O"... is not valid JSON". O que está errado? R: Este erro ocorre quando o arquivo de configuração JSON do cliente está malformado. Causas comuns:

  1. Vírgulas ausentes ou extras no JSON
  2. Barras invertidas não escapadas em caminhos do Windows
  3. Comentários no JSON (JSON não suporta comentários)

Verifique seu arquivo de configuração do cliente (por exemplo, claude_desktop_config.json):

  1. Use um validador JSON (como jsonlint.com) para verificar a sintaxe
  2. Para caminhos do Windows, escape barras invertidas: "C:\\path\\to\\file"
  3. Remova quaisquer comentários (// ou /* */)
  4. Garanta que todas as strings estejam devidamente citadas
  5. Verifique se todos os colchetes e chaves estão devidamente fechados

Exemplo de formatação correta de caminho do Windows:

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"]
    }
  }
}

P: Recebo um erro de tempo limite e a mensagem "Servidor desconectado". O que está acontecendo? R: Este padrão de erro (inicialização bem-sucedida, depois tempo limite após 60 segundos) geralmente significa:

  1. O servidor já está em execução em outro processo
  2. A porta já está em uso por outro aplicativo
  3. O processo do servidor está sendo encerrado inesperadamente

Tente estes passos em ordem:

  1. Verifique processos de servidor em execução:

    # On Windows
netstat -ano | findstr :8001
# Look for the PID and then:
taskkill /F /PID <PID>

    # On Linux/macOS
lsof -i :8001
# Look for the PID and then:
kill -9 <PID>

  2. Verifique outros aplicativos usando a porta:

    • Feche quaisquer outros aplicativos que possam usar a porta 8001
    • Isso inclui outros servidores MCP, servidores de desenvolvimento ou quaisquer aplicativos web
    • Se não tiver certeza, tente mudar a porta no seu .env: 
      OMCP_SERVER_PORT=8002

  3. Verifique o processo do servidor:

    • Abra o Gerenciador de Tarefas (Windows) ou o Monitor de Atividade (macOS)
    • Procure por quaisquer processos Python relacionados ao servidor MCP
    • Encerre quaisquer processos suspeitos

  4. Verifique os recursos do sistema:

    • Garanta que você tenha memória e CPU suficientes disponíveis
    • Verifique se algum antivírus ou software de segurança está bloqueando o processo
    • Verifique se seu ambiente Python tem permissões adequadas

  5. Redefina tudo:

    • Pare o aplicativo cliente
    • Encerre quaisquer processos de servidor restantes
    • Exclua o arquivo .env e crie um novo a partir de .env.example
    • Reinicie seu computador (se outros passos não funcionarem)
    • Comece do zero com o aplicativo cliente

Se o problema persistir após tentar todos esses passos, compartilhe:

  1. O log de erro completo
  2. A saída de netstat -ano | findstr :8001 (Windows) ou lsof -i :8001 (Linux/macOS)
  3. Quaisquer mensagens de erro dos logs de eventos do seu sistema P: O servidor desconecta imediatamente com "Server transport closed unexpectedly... process exiting early". O que está errado? R: Esse erro significa que o processo do servidor Python travou quase imediatamente após ser iniciado pelo cliente. Não é um timeout; o próprio script do servidor falhou ao executar ou permanecer em execução.

Causas comuns:

  1. Caminhos incorretos no JSON do cliente:
    • command não aponta para o python.exe correto dentro do .venv.
    • args não aponta para o script obsidian_mcp_server/main.py correto.
    • Separadores de caminho incorretos ou escapes de barra invertida ausentes (\\) no Windows.
  2. Dependências ausentes:
    • Pacotes necessários do requirements.txt não estão instalados no .venv.
    • O cliente está iniciando o Python sem ativar corretamente o ambiente virtual.
  3. Erros de sintaxe: Uma alteração recente no código introduziu um erro de sintaxe no Python.
  4. Erro crítico de configuração/permissão:
    • Erro ao ler o arquivo .env na inicialização.
    • OMCP_VAULT_PATH inválido ou inacessível.
    • O processo Python não tem permissões para executar ou acessar arquivos.
  5. Exceção não tratada precoce: Ocorre um erro durante a configuração inicial antes de o servidor começar a escutar.

Etapas de solução de problemas:

  1. Verifique os caminhos no JSON do cliente: Verifique novamente os caminhos absolutos para command e args na configuração JSON do seu cliente. Use barras invertidas escapadas (\\) para caminhos do Windows.
  2. Teste manualmente (etapa crucial):
    • Ative o ambiente virtual no seu terminal: 
      # On Windows
.\.venv\Scripts\activate

      # On Linux/macOS
source .venv/bin/activate
    • Execute o servidor diretamente: 
      python obsidian_mcp_server/main.py
    • Observe atentamente se há mensagens de erro impressas diretamente no terminal. Isso ignora o cliente e frequentemente revela a causa raiz (como ImportError, SyntaxError, FileNotFoundError).
  3. Verifique as dependências: Com o venv ativado, execute pip check e pip install -r requirements.txt.
  4. Valide .env e o caminho do cofre: Garanta que .env exista, seja legível e que OMCP_VAULT_PATH esteja correto (use barras normais /).
  5. Revise alterações recentes no código: Verifique se há erros de sintaxe ou problemas em arquivos Python editados recentemente.

Operações de Nota

P: Por que não consigo criar/editar notas em certas pastas? R: Isso pode ser devido a:

  1. Restrições de segurança de caminho (tentativa de escrever fora do cofre)
  2. Permissões de pasta
  3. Bloqueios de arquivo por outros processos

Tente:

  1. Usar caminhos relativos dentro do seu cofre
  2. Verificar as permissões da pasta
  3. Fechar outros programas que possam ter os arquivos abertos

P: Por que minhas atualizações de notas não estão sendo salvas? R: Causas comuns:

  1. O caminho da nota está incorreto
  2. O formato do conteúdo é inválido
  3. A criação do backup falhou

Verifique:

  1. Se o caminho da nota existe e é acessível
  2. Se o conteúdo é markdown válido
  3. Se o diretório de backup tem permissões de escrita

Notas Diárias

P: Por que minhas notas diárias não estão sendo criadas no local correto? R: Verifique:

  1. Se OMCP_DAILY_NOTE_LOCATION está definido corretamente em .env
  2. Se o caminho usa barras normais
  3. Se a pasta de destino existe
  4. Se o formato da data corresponde às configurações do seu cofre

Solução de Problemas Gerais

P: Como verifico se o servidor está funcionando corretamente? R: Execute o cliente de teste:

python test_client.py

Isso realizará uma série de operações e relatará quaisquer problemas.

P: Onde posso encontrar logs de erro? R: Verifique:

  1. O terminal onde o servidor está em execução
  2. O diretório de backup para operações com falha
  3. Os logs de eventos do sistema para problemas de permissão

P: Como faço para redefinir tudo e começar do zero? R: Tente estas etapas:

  1. Pare o servidor
  2. Exclua o arquivo .env
  3. Crie um novo .env a partir de .env.example
  4. Reinicie o servidor

Contribuições são bem-vindas!