Obsidian

Interaja com seu cofre do Obsidian usando linguagem natural.

Documentação

Servidor MCP Obsidian

Um poderoso servidor Model Context Protocol (MCP) para interação em linguagem natural com seu cofre Obsidian. Construído com TypeScript e projetado para integração perfeita com Claude Code e outros clientes MCP.

Recursos

Capacidades Principais

Consultas em Linguagem Natural: Faça perguntas sobre seu cofre em inglês simples
Busca Avançada: Busca inteligente com análise de links, hierarquias de tags e contexto estrutural
Análise de Backlinks: Encontre e analise conexões entre notas
Navegação no Cofre: Explore a estrutura de diretórios e descubra notas
Operações CRUD Completas: Leia, escreva, crie, acrescente e atualize notas

Ferramentas de Inteligência Avançada

Trilha de História Guiada: Gere tours narrativos por notas vinculadas
Auditoria de Notas: Encontre notas modificadas recentemente sem frontmatter ou estrutura
Companheiros Contextuais: Descubra notas relacionadas com base em links, palavras-chave e recência
Energia Fresca: Identifique notas atualizadas recentemente que precisam de integração
Ponte de Iniciativa: Rastreie notas específicas de projetos com tarefas pendentes
Eco de Padrões: Encontre notas que reutilizam frases ou padrões específicos
Pronto para Síntese: Detecte clusters de notas que precisam de notas de resumo

Instalação

A partir do Código Fonte

Clone o repositório:

git clone https://github.com/dbmcco/obsidian-mcp.git
cd obsidian-mcp

Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```

Configuração

Configuração do Claude Code

Adicione à sua configuração MCP do Claude Code:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Variáveis de Ambiente

OBSIDIAN_VAULT_PATH: Obrigatório. Caminho absoluto para o seu cofre Obsidian

Ferramentas Disponíveis

Operações Básicas

query_vault

Processa consultas em linguagem natural sobre o conteúdo do seu cofre.

Exemplo: "Quais são os principais temas nas minhas notas de projeto?"

{
  query: string,
  vaultPath?: string  // Optional override
}

search_notes

Busca notas por nome de arquivo ou conteúdo usando correspondência exata de texto.

{
  searchTerm: string,
  searchType: 'filename' | 'content' | 'both',  // Default: 'both'
  vaultPath?: string
}

intelligent_search

Busca avançada com análise de grafo de links, hierarquias de tags e ponderação de contexto estrutural.

{
  query: string,
  vaultPath?: string
}

list_directories

Explore a estrutura de diretórios do cofre com contagens de notas.

{
  directoryPath?: string,  // Empty string for vault root
  vaultPath?: string
}

get_note

Recupera o conteúdo completo de uma nota específica.

{
  notePath: string,  // Relative to vault root
  vaultPath?: string
}

get_backlinks

Encontra todas as notas que vinculam a uma nota específica com contexto.

{
  notePath: string,
  vaultPath?: string
}

Operações de Escrita

write_note

Escreve ou sobrescreve completamente uma nota.

{
  notePath: string,
  content: string,
  vaultPath?: string
}

create_note

Cria uma nova nota com frontmatter e conteúdo.

{
  notePath: string,
  title: string,
  content?: string,
  tags?: string[],
  vaultPath?: string
}

append_to_note

Adiciona conteúdo a uma nota existente.

{
  notePath: string,
  content: string,
  vaultPath?: string
}

update_note_section

Atualiza uma seção específica identificada por título.

{
  notePath: string,
  sectionHeading: string,
  newContent: string,
  vaultPath?: string
}

Inteligência Avançada

guided_path

Gera um tour narrativo por notas vinculadas a partir de uma nota inicial.

{
  notePath: string,
  supportingLimit?: number,      // Default: 3
  counterpointLimit?: number,    // Default: 3
  includeActionItems?: boolean,  // Default: true
  vaultPath?: string
}

Saída: Narrativa em Markdown com introdução, tópicos de apoio, contrapontos e itens de ação.

audit_recent_notes

Encontra notas modificadas recentemente sem frontmatter ou estrutura.

{
  hoursBack?: number,           // Default: 72
  limit?: number,               // Default: 25
  requiredFields?: string[],    // Default: ['title', 'created']
  requireHeadings?: boolean,    // Default: false
  vaultPath?: string
}

contextual_companions

Descobre notas relacionadas a um tópico ou nota inicial com base em links, palavras-chave e recência.

{
  notePath?: string,    // Optional seed note
  topic?: string,       // Optional topic query
  limit?: number,       // Default: 5
  vaultPath?: string
}

Nota: Forneça notePath ou topic.

fresh_energy

Encontra notas atualizadas recentemente sem backlinks ou links de saída (precisando de integração).

{
  hoursBack?: number,   // Default: 48
  limit?: number,       // Default: 10
  minWords?: number,    // Default: 80
  vaultPath?: string
}

initiative_bridge

Rastreia notas com marcação de projeto/iniciativa que possuem tarefas pendentes.

{
  initiative: string,           // Required: project identifier
  frontmatterField?: string,    // Default: 'project'
  limit?: number,               // Default: 10
  vaultPath?: string
}

pattern_echo

Encontra notas que reutilizam frases específicas, padrões de marcadores ou fragmentos de estruturas.

{
  snippet: string,      // Required: text pattern to find
  limit?: number,       // Default: 5
  vaultPath?: string
}

synthesis_ready

Detecta clusters de notas interligadas que não possuem uma nota de resumo/síntese.

{
  minClusterSize?: number,  // Default: 3
  vaultPath?: string
}

Exemplos de Casos de Uso

Descoberta de Conhecimento

// Find all notes about a topic with intelligent expansion
await intelligentSearch({ query: "machine learning" });

// Discover related notes for further reading
await contextualCompanions({
  topic: "neural networks",
  limit: 10
});

Manutenção do Cofre

// Audit recent work for missing metadata
await auditRecentNotes({
  hoursBack: 168,  // Last week
  requiredFields: ['title', 'created', 'tags']
});

// Find orphaned notes needing links
await freshEnergy({ hoursBack: 72 });

// Identify note clusters needing synthesis
await synthesisReady({ minClusterSize: 4 });

Gerenciamento de Projetos

// Track all tasks for a specific project
await initiativeBridge({
  initiative: "Project Alpha",
  frontmatterField: "project"
});

// Generate a narrative overview of a topic
await guidedPath({
  notePath: "Projects/Project Alpha.md",
  supportingLimit: 5,
  includeActionItems: true
});

Análise de Padrões

// Find notes using a specific framework
await patternEcho({
  snippet: "SWOT Analysis:",
  limit: 10
});

Desenvolvimento

Scripts

npm run dev: Modo de observação para desenvolvimento
npm run build: Compile TypeScript para JavaScript
npm run start: Inicie o servidor MCP

Estrutura do Projeto

obsidian-mcp/
├── src/
│   ├── index.ts           # MCP server and tool definitions
│   ├── vault-manager.ts   # Vault operations and intelligence
│   └── query-processor.ts # Natural language query processing
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Detalhes Técnicos

Arquitetura

TypeScript com modo estrito habilitado
ES Modules (NodeNext)
Zod para validação de tipos em tempo de execução
gray-matter para análise de frontmatter
glob para correspondência de padrões de arquivos

Métodos de Busca

A ferramenta intelligent_search combina quatro estratégias de busca:

Correspondência direta: Correspondências exatas de palavras-chave no conteúdo/nomes de arquivo
Proximidade de links: Notas conectadas via wiki-links
Expansão de tags: Notas relacionadas via hierarquias de tags
Contexto estrutural: Busca ciente de seções com pontuação de relevância

Os resultados são mesclados, deduplicados e classificados por pontuação de relevância.

Performance

Sem cache - todas as buscas são em tempo real para evitar dados desatualizados
Carregamento preguiçoso do conteúdo das notas para cofres grandes
Padrões glob eficientes para descoberta de arquivos

Créditos

Construído por Braydon com Claude (Anthropic). Este servidor MCP foi desenvolvido usando princípios de desenvolvimento orientado a testes e colaboração extensiva com Claude Code.

Licença

Licença MIT - Sinta-se livre para usar e modificar conforme necessário.

Contribuindo

Contribuições são bem-vindas! Por favor:

Faça um fork do repositório
Crie uma branch de feature
Faça suas alterações com testes
Envie um pull request

Solução de Problemas

Erro "Nenhum caminho de cofre fornecido"

Garanta que OBSIDIAN_VAULT_PATH esteja definido na sua configuração MCP ou nas variáveis de ambiente.

Servidor MCP não conectando

Verifique se o caminho para dist/index.js é absoluto, não relativo
Garanta que o servidor esteja compilado (npm run build)
Verifique se o Node.js consegue executar o script

Busca não retorna resultados

Verifique se o caminho do cofre está correto
Verifique se os arquivos .md existem no cofre
Tente usar list_directories para explorar a estrutura do cofre