Notes MCP Server

Servidor Notes MCP

Um servidor MCP (Model Context Protocol) para interagir com notas do Obsidian. Este servidor fornece ferramentas para pesquisar e ler notas do seu cofre Obsidian, tornando sua base de conhecimento acessível a assistentes de IA.

Recursos

• Pesquisar Notas: Pesquisa de texto completo no seu cofre Obsidian usando ripgrep
• Ler Notas: Analisa e extrai conteúdo, metadados e tags das notas
• Multiplataforma: Funciona em Windows, macOS e Linux
• Suporte a Frontmatter: Extrai frontmatter YAML como metadados estruturados
• Extração de Tags: Identifica e extrai automaticamente tags do Obsidian

Pré-requisitos

• Runtime Deno
• ripgrep (comando rg)
• Um cofre Obsidian com arquivos markdown

Configuração

1. Clone ou baixe este projeto
2. Defina a variável de ambiente OBSIDIAN_VAULT_PATH:

   export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
   

3. Execute o servidor:

   # Using Deno directly
   deno task start
   
   # Using mise (if you have mise installed)
   mise run start
   

Desenvolvimento

Para desenvolvimento com monitoramento de arquivos:

# Using Deno
deno task dev

# Using mise
mise run dev

Testes

Você pode testar o servidor MCP usando a ferramenta CLI de consulta incluída:

# Search for notes containing a pattern (case-insensitive by default)
mise run query search "productivity"

# Case-sensitive search
mise run query search "TODO" --case-sensitive

# Search for whole words only
mise run query search "test" --whole-word

# Multiline search
mise run query search "pattern.*spans.*lines" --multiline

# Search with custom context lines (default: 5)
mise run query search "pattern" --context 10

# Read specific notes
mise run query read "daily-notes/2024-01-15"
mise run query read "note1" "folder/note2"

# Use verbose mode to see the request being sent
mise run query -v search "pattern"
mise run query --verbose read "note1"

A ferramenta de consulta conecta-se ao servidor MCP e retorna as respostas JSON brutas, sendo útil para testes e depuração.

Ferramentas

search_notes

Pesquisa arquivos markdown no seu cofre usando padrões do ripgrep.

Parâmetros:

• pattern (string, obrigatório): Padrão de pesquisa para ripgrep
• flags (array, opcional): Flags adicionais do ripgrep

Retorna: Array de resultados de pesquisa com:

• path: Caminho relativo da nota (sem extensão .md)
• matches: Array de correspondências com números de linha e contexto

read_notes

Lê e analisa uma ou mais notas do seu cofre.

Parâmetros:

• paths (array, obrigatório): Array de caminhos relativos de notas (com ou sem extensão .md)

Retorna: Array de objetos de nota com:

• name: Nome da nota (caminho relativo sem extensão .md)
• contents: Conteúdo Markdown (sem frontmatter e tags)
• metadata: Frontmatter analisado como objeto JSON
• tags: Array de tags do Obsidian extraídas

Exemplo de Uso

Uma vez conectado a um cliente MCP, você pode:

// Search for notes containing "productivity"
await search_notes({
  pattern: "productivity",
  flags: ["-i"] // case-insensitive
});

// Read specific notes
await read_notes({
  paths: ["daily-notes/2024-01-15", "projects/my-project"]
});

Configuração

O servidor requer que a variável de ambiente OBSIDIAN_VAULT_PATH seja definida para o diretório do seu cofre Obsidian.

Integração com Claude Desktop

Para usar este servidor MCP com o Claude Desktop, adicione-o ao seu arquivo de configuração do Claude:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notes": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read=/path/to/your/obsidian/vault",
        "--allow-run=rg",
        "--allow-env=OBSIDIAN_VAULT_PATH",
        "src/index.ts"
      ],
      "cwd": "/path/to/notes-mcp",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Usando mise (recomendado se você tiver o mise instalado):

{
  "mcpServers": {
    "notes": {
      "command": "/path/to/notes-mcp/start-server.sh",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Isso usa o script start-server.sh incluído, que lida com a mudança para o diretório do projeto e a execução do mise run start.

Substitua os caminhos por:

• /path/to/notes-mcp: O caminho absoluto para o diretório deste projeto
• /path/to/your/obsidian/vault: O caminho absoluto para o seu cofre Obsidian

Após atualizar a configuração, reinicie o Claude Desktop. O servidor aparecerá como "notes" e fornecerá as ferramentas search_notes e read_notes.