Obsidian MCP

Leia, escreva, pesquise e navegue em suas notas do Obsidian usando linguagem natural

Documentação

obsidian-mcp

Um servidor MCP (Model Context Protocol) que dá aos assistentes de IA acesso direto ao seu cofre do Obsidian. Leia, escreva, pesquise e navegue por notas usando linguagem natural — com qualquer cliente compatível com MCP.

Pré-requisitos

Node.js 18+ — nodejs.org
Um cofre do Obsidian (uma pasta de arquivos .md — nenhum aplicativo Obsidian é necessário em tempo de execução)

Instalação

Você não executa o servidor manualmente — seu cliente de IA (Claude Desktop, Cursor, etc.) o inicia automaticamente quando é aberto. Tudo o que você precisa fazer é compilar o projeto uma vez e apontar a configuração do seu cliente para o arquivo de saída.

1. Clone e compile:

git clone <repo-url> obsidian-mcp
cd obsidian-mcp
npm install
npm run build

Isso gera dist/index.js — o arquivo que toda configuração de cliente fará referência.

2. Encontre o caminho do seu cofre. Esta é a pasta que o Obsidian abre como seu cofre, ex.: /Users/yourname/Documents/MyVault.

3. Siga a configuração do seu cliente abaixo. Cada configuração informa ao cliente:

onde está o arquivo compilado (dist/index.js)
qual cofre usar (OBSIDIAN_VAULT_PATH)

Configuração do Cliente

Todos os clientes usam transporte stdio — o servidor roda como um subprocesso local na sua máquina. Nenhuma hospedagem é necessária.

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Saia e reabra o Claude Desktop. Um ícone de martelo (🔨) no campo de entrada do chat confirma que o servidor está conectado.

Claude Code (CLI)

Registre o servidor com o comando claude mcp add:

claude mcp add obsidian \
  node /absolute/path/to/obsidian-mcp/dist/index.js \
  -e OBSIDIAN_VAULT_PATH=/path/to/your/vault

Verifique se está registrado:

claude mcp list

As ferramentas agora estão disponíveis em qualquer sessão do Claude Code.

Cursor

Abra Configurações → Configurações do Cursor → MCP (ou edite ~/.cursor/mcp.json):

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

Reinicie o Cursor. As ferramentas aparecem automaticamente no chat de IA e no Composer do Cursor.

VS Code

O VS Code suporta servidores MCP por meio de várias extensões. A configuração vai em .vscode/mcp.json (escopo do projeto) ou no seu settings.json de usuário (global).

GitHub Copilot (VS Code 1.99+)

Crie .vscode/mcp.json no seu projeto, ou adicione em Configurações do Usuário (JSON):

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

No GitHub Copilot Chat, mude para o modo Agente (@workspace) — as ferramentas do obsidian estarão disponíveis automaticamente.

Cline

Abra o painel de configurações do Cline → Servidores MCP → Adicionar Servidor → cole:

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

Continue

Edite ~/.continue/config.json:

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

Zed

Edite ~/.config/zed/settings.json:

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

As ferramentas estão disponíveis no painel do Assistente de IA do Zed.

Ollama (via mcphost)

O Ollama não suporta MCP nativamente. Use mcphost como uma ponte — ele encapsula qualquer servidor MCP e o conecta a um modelo local do Ollama.

1. Instale o mcphost:

go install github.com/mark3labs/mcphost@latest

2. Crie um arquivo de configuração (~/.mcphost/config.json):

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

3. Inicie uma sessão de chat com qualquer modelo do Ollama:

mcphost --model ollama:qwen2.5:14b

A qualidade do uso de ferramentas depende muito do modelo. Recomendados: qwen2.5:14b, llama3.1:8b, mistral-nemo. Os modelos precisam suportar chamadas de função/ferramenta para usar as ferramentas MCP de forma confiável.

Ferramentas Disponíveis

Ferramenta	Descrição
`obsidian_list_notes`	Lista notas no cofre, opcionalmente filtradas por pasta. Paginado.
`obsidian_read_note`	Lê o conteúdo completo de uma nota pelo caminho relativo ao cofre.
`obsidian_create_note`	Cria uma nova nota com frontmatter YAML opcional.
`obsidian_update_note`	Sobrescreve o conteúdo e o frontmatter de uma nota existente.
`obsidian_append_to_note`	Adiciona conteúdo a uma nota (cria se não existir).
`obsidian_delete_note`	Exclui permanentemente uma nota.
`obsidian_move_note`	Move ou renomeia uma nota para um novo caminho.
`obsidian_get_note_metadata`	Lê apenas o frontmatter e as tags, sem carregar o corpo.
`obsidian_search_notes`	Pesquisa de texto completo em todas as notas (sem diferenciar maiúsculas de minúsculas).
`obsidian_search_by_tag`	Encontra todas as notas com um `#tag` específico.
`obsidian_get_backlinks`	Encontra todas as notas que `[[link]]` para uma determinada nota.
`obsidian_list_folders`	Lista pastas no cofre com contagens de notas.
`obsidian_create_folder`	Cria uma nova pasta (as pastas pai são criadas automaticamente).

Todas as ferramentas aceitam um parâmetro response_format: "markdown" (padrão, legível por humanos) ou "json" (estruturado, para uso programático).

Exemplos de prompts

"Summarise everything in my projects folder"
"Create a note called 'Meeting Notes 2025-04-11' with today's agenda"
"Find all notes tagged #todo and list what's incomplete"
"What notes link back to my 'Home' note?"
"Search for anything mentioning the Q2 launch"
"Append '- [ ] Follow up with design team' to my Daily Note"

Segurança

Proteção contra travessia de caminho — todos os caminhos são validados para permanecer dentro de OBSIDIAN_VAULT_PATH
Proteção contra symlink — symlinks dentro do cofre que apontam para fora dele são bloqueados
Limite de tamanho de arquivo — notas maiores que 5 MB são rejeitadas para evitar esgotamento de memória
Limite de tamanho de resposta — respostas são truncadas em 25.000 caracteres com um aviso claro
Sem acesso à rede — o servidor lê e escreve apenas arquivos locais; nenhuma solicitação de saída

Extensão

O código é modular por design. Para adicionar um novo conjunto de ferramentas:

Crie src/tools/my-feature.ts e exporte uma função registerMyFeatureTools(server, vault)
Adicione-a em src/tools/index.ts:

import { registerMyFeatureTools } from './my-feature.js';

export function registerAllTools(server: McpServer, vault: VaultService): void {
  registerNoteTools(server, vault);
  registerSearchTools(server, vault);
  registerFolderTools(server, vault);
  registerMyFeatureTools(server, vault);  // ← add this
}

Execute npm run build

Para adicionar capacidades ao cofre (ex.: leitura de arquivos canvas, expansão de modelos), estenda VaultService em src/services/vault.ts e chame os novos métodos a partir dos seus manipuladores de ferramentas.