Obsidian MCP Local

MCP local em Node.js + TypeScript para expor seu vault do Obsidian ao VS Code + GitHub Copilot.

Ele foi pensado para uso local via stdio, com foco em ler e escrever notas Markdown dentro do seu vault.

Install

npm install -g obsidian-mcp-local

Features

Tools disponíveis

• search_notes(query)

  • busca por texto no path, frontmatter e conteúdo das notas
  • retorna resultados ranqueados com pequeno excerpt

• get_note(path)

  • abre uma nota do vault
  • retorna path, frontmatter e content

• create_note(path, content, overwrite?)

  • cria uma nota nova
  • opcionalmente sobrescreve uma nota existente

• append_to_note(path, content)

  • adiciona conteúdo no final de uma nota existente

• find_by_tag(tag)

  • encontra notas por tag
  • suporta tags no frontmatter e tags inline no conteúdo

Regras implementadas

• só acessa arquivos dentro do vault configurado
• ignora diretórios como:
  • .obsidian
  • .git
  • node_modules
• trabalha apenas com arquivos .md
• normaliza paths para evitar acesso fora do diretório base

Estrutura do projeto

obsidian-mcp-local/
  package.json
  tsconfig.json
  README.md
  .vscode/
    mcp.example.json
  src/
    index.ts

Pré-requisitos

• Node.js 20+
• npm
• VS Code com GitHub Copilot
• um vault do Obsidian local

Instalação

No diretório do projeto:

npm install
npm run build

Para desenvolvimento:

npm run dev

Para rodar a versão compilada:

npm start

Como usar no VS Code

1. Compile o projeto

npm install
npm run build

2. Ajuste o arquivo MCP do VS Code

Copie o conteúdo de .vscode/mcp.example.json para o seu .vscode/mcp.json no workspace onde você vai usar o Copilot.

Exemplo: utilizando localmente:

{
  "servers": {
    "obsidian-local-vault": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/caminho/para/obsidian-mcp-local/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "D:/Obsidian/Vault"
      }
    }
  }
}

utilizando via npx (sem necessidade de build local):

{
  "servers": {
    "obsidian-local-vault": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-local"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "D:/Obsidian/Vault"
      }
    }
  }
}

3. Atualize os caminhos

Substitua:

• C:/caminho/para/obsidian-mcp-local/dist/index.js
• D:/Obsidian/Vault

pelos caminhos reais da sua máquina.

4. Reinicie/recarrregue o VS Code

Depois disso, o Copilot deve descobrir o servidor MCP.

Exemplos de uso no Copilot Chat

• “Procure no meu vault notas sobre .NET”
• “Abra a nota knowledge/backend/dotnet.md”
• “Crie uma nota em inbox/ideias-mcp.md com um resumo do que discutimos”
• “Adicione no final da nota daily/2026-04-06.md o texto - testar MCP local”
• “Encontre notas com a tag #arquitetura”

Possíveis melhorias futuras

• append_under_heading
• parsing de [[wikilinks]]
• get_backlinks(note)
• índice em SQLite para busca rápida
• whitelist de pastas para escrita (inbox/, daily/, scratch/)
• bloqueio configurável de escrita em determinadas pastas

Observações importantes

• Este projeto não depende do Obsidian aberto.
• Ele opera diretamente sobre os arquivos do vault.
• Se você habilitar escrita tanto no Obsidian quanto no VS Code, o controle de concorrência fica por sua conta.
• O projeto hoje assume que o vault é uma pasta Markdown local.

Arquivo principal

A implementação está em:

• src/index.ts

Licença

Uso pessoal / base inicial para customização.