Obsidian MCP

Plugin para Obsidian Desktop que permite a agentes de IA, como o Codex, acessar notas Markdown e criar pastas autorizadas no vault por meio do Model Context Protocol (MCP).

O servidor roda localmente com Streamable HTTP e autenticação por token. O projeto inclui um CLI para instalar, atualizar, diagnosticar e remover o plugin, além de configurar a integração com o Codex.

Funcionalidades · Requisitos · Instalação · Configuração · Ferramentas MCP · Diagnóstico · Contribuição

Funcionalidades

• Listar, ler, pesquisar e criar notas Markdown pela API oficial do Obsidian.

• Criar pastas dentro dos diretórios autorizados em allowedFolders.

• Restringir o acesso a pastas escolhidas pelo usuário, incluindo suas subpastas.

• Exigir token Bearer e aceitar conexões somente em 127.0.0.1.

• Bloquear caminhos fora das permissões, arquivos ocultos e links simbólicos.

• Iniciar e encerrar o servidor junto com o plugin.

• Instalar artefatos locais ou releases públicas do GitHub, com verificação SHA-256.

• Configurar o Codex automaticamente, preservando configurações existentes e oferecendo uma alternativa manual.

O plugin não possui painel de configurações. As permissões de acesso são definidas em data.json.

Related MCP server: obsidian-mcp-server

Requisitos

O Node.js é necessário para o CLI e a compilação; o plugin instalado executa no runtime do Obsidian.

Instalação

Local

Na raiz de uma cópia do repositório:

npm ci
npm run build
npm link
obsidian-mcp install

O instalador oferece os vaults registrados pelo Obsidian no sistema (incluindo Flatpak no Linux) e permite digitar outro caminho. Para selecionar o vault diretamente:

obsidian-mcp install --vault "/caminho/do/vault" --source local

Sem registrar o comando no PATH com npm link, use npm run cli -- install --vault "/caminho/do/vault" após o build.

O CLI instala main.js e manifest.json em .obsidian/plugins/obsidian-mcp/, prepara data.json, registra a ativação e configura o Codex. Em Linux/macOS, aplica 0600 ao data.json; no Windows, restringe sua ACL ao usuário atual e a SYSTEM. O conteúdo existente é preservado.

Remota: Linux e macOS

Os instaladores baixam e verificam o CLI, instalam um launcher por usuário e delegam a instalação do plugin ao CLI. Não é necessário clonar o repositório, usar npm ou compilar. Não requerem sudo nem alteram os perfis do shell.

Os exemplos abaixo serão utilizáveis após a publicação de uma release contendo os instaladores. A origem padrão é ernando760/obsidian-mcp. Substitua 0.1.0 pela tag exata da release desejada. A origem oficial é declarada em package.json.repository e incorporada ao CLI e aos scripts preparados para a release. A URL configurada é https://github.com/ernando760/obsidian-mcp.git; o repositório público e o envio inicial de main já foram confirmados. Argumentos e OBSIDIAN_MCP_REPOSITORY continuam permitindo selecionar outra origem.

Baixe e confira o próprio script antes de executá-lo. A verificação abaixo usa sha256sum no Linux ou shasum no macOS:

REPO='ernando760/obsidian-mcp'
TAG='0.1.0'
curl -fL "https://github.com/$REPO/releases/download/$TAG/install.sh" -o install.sh &&
curl -fL "https://github.com/$REPO/releases/download/$TAG/SHA256SUMS" -o SHA256SUMS &&
if command -v sha256sum >/dev/null 2>&1; then
  awk '$2 == "install.sh" { print }' SHA256SUMS | sha256sum --check -
else
  awk '$2 == "install.sh" { print }' SHA256SUMS | shasum -a 256 --check -
fi &&
sh ./install.sh --repo "$REPO" --version "$TAG"

A precedência é argumento explícito, variável OBSIDIAN_MCP_REPOSITORY e origem oficial incorporada. No comando update do CLI, uma origem já registrada é reaproveitada antes do padrão oficial.

Sem --vault, o CLI detecta os vaults registrados ou solicita o caminho em um terminal interativo. Para informar o vault diretamente:

# Linux
sh ./install.sh --repo "$REPO" --version "$TAG" --vault "$HOME/Documentos/Meu Vault"
# macOS
sh ./install.sh --repo "$REPO" --version "$TAG" --vault "$HOME/Documents/Meu Vault"

O launcher fica em ~/.local/bin/obsidian-mcp. Se esse diretório não estiver no PATH, use o caminho completo, por exemplo ~/.local/bin/obsidian-mcp doctor. --install-dir e --bin-dir permitem escolher outros destinos, inclusive caminhos com espaços.

Remota: Windows

Use PowerShell 5.1 ou posterior, com Node.js 22.12+ disponível no PATH. Execute como seu usuário normal; não é necessário abrir o terminal como administrador.

$Repo = 'ernando760/obsidian-mcp'
$Tag = '0.1.0'
Invoke-WebRequest -UseBasicParsing "https://github.com/$Repo/releases/download/$Tag/install.ps1" -OutFile install.ps1 -ErrorAction Stop
Invoke-WebRequest -UseBasicParsing "https://github.com/$Repo/releases/download/$Tag/SHA256SUMS" -OutFile SHA256SUMS -ErrorAction Stop
$Entries = @(Get-Content SHA256SUMS | Where-Object { $_ -cmatch '^([a-f0-9]{64}) [ *]install\.ps1$' })
$Actual = (Get-FileHash .\install.ps1 -Algorithm SHA256).Hash.ToLowerInvariant()
if ($Entries.Count -ne 1 -or $Entries[0].Substring(0, 64) -cne $Actual) { throw 'Checksum do instalador inválido' }
Unblock-File -LiteralPath .\install.ps1
.\install.ps1 -Repo $Repo -Version $Tag -Vault 'C:\Users\SeuUsuario\Documents\Meu Vault'

Omita -Vault para a descoberta e seleção interativa. O script não altera a política global de execução nem o PATH. O launcher fica em %LOCALAPPDATA%\ObsidianMCP\obsidian-mcp.cmd; use o caminho completo se o diretório não estiver no PATH:

& "$env:LOCALAPPDATA\ObsidianMCP\obsidian-mcp.cmd" doctor --vault 'C:\Users\SeuUsuario\Documents\Meu Vault'

Use -InstallDir 'D:\Ferramentas\Obsidian MCP' para outro destino. O CLI protege credenciais com ACLs nativas, verificadas pelo doctor; o destino deve oferecer suporte a ACLs, como em volumes NTFS. chmod 600 não representa essa proteção no Windows, conforme as limitações de permissões do Node.js.

Opções dos scripts e integridade

A release inclui install.sh, install.ps1, obsidian-mcp-cli.mjs, main.js, manifest.json e SHA256SUMS. Os scripts verificam o SHA-256 do CLI antes de executá-lo; em seguida, o CLI verifica os artefatos do plugin. Releases preliminares e rascunhos são recusados. A confiança na origem continua sendo a confiança no repositório e na release escolhidos.

A instalação configura o Codex automaticamente, reaproveita tokens e permissões de notas existentes e informa quando falta recarregar o Obsidian. Para uma alternativa totalmente manual, baixe main.js e manifest.json da mesma release, confira seus hashes em SHA256SUMS e copie-os para a pasta do plugin conforme a seção seguinte.

Ativação e opções do instalador

Abra o vault no Obsidian, permita plugins da comunidade e confira se Obsidian MCP está ativo. Se o aplicativo já estava aberto, recarregue o plugin ou feche e reabra o vault. O CLI verifica o carregamento por uma conexão MCP autenticada e informa quando a ativação ainda está pendente.

Use obsidian-mcp --help para consultar os comandos. Como alternativa ao CLI, copie main.js e manifest.json para a pasta do plugin e ative-o no Obsidian; o primeiro carregamento gera data.json. A conexão Codex pode ser configurada conforme a seção abaixo.

Configuração e integração com o Codex

Pastas autorizadas

A pasta MCP/ não é obrigatória para o funcionamento do plugin. Qualquer pasta permitida pela política de caminhos pode ser autorizada em allowedFolders.

O padrão inicial é ["MCP"]. Quando não existe data.json, o CLI também cria essa pasta como configuração inicial. Atualmente, não há uma opção do CLI para escolher allowedFolders; para utilizar outras pastas, ajuste o arquivo de configuração.

1. Desative o plugin no Obsidian.

2. Edite <vault>/.obsidian/plugins/obsidian-mcp/data.json, mantendo o token gerado.

3. Configure as pastas desejadas e reative o plugin.

Exemplo de configuração — substitua o token ilustrativo pelo valor existente:

{
  "port": 27124,
  "token": "COLE_AQUI_O_TOKEN_GERADO_DE_64_CARACTERES_HEXADECIMAIS",
  "allowedFolders": ["Notas", "Projetos/Compartilhados"]
}

Nesse exemplo, os agentes podem acessar Notas/reuniao.md e Projetos/Compartilhados/plano.md, incluindo notas em suas subpastas. A pasta MCP/ pode ficar fora da configuração e ser removida se estiver vazia.

Não são aceitos a raiz do vault, caminhos absolutos, segmentos .., pastas ocultas, links simbólicos ou o diretório de configuração do Obsidian. As pastas usadas para leitura devem existir; para criar uma pasta autorizada, use create_folder com a pasta pai já existente.

Uma instalação nova pelo CLI procura uma porta livre entre 27124 e 27223; --port permite escolher outra sem fazer bind de teste. A instalação manual usa 27124 por padrão. O servidor atende em http://127.0.0.1:<porta>/mcp.

Integração automática

O instalador usa codex mcp add quando disponível e completa a autenticação em config.toml. Se a CLI do Codex não estiver instalada, configura o arquivo diretamente.

A configuração fica em ~/.codex/config.toml, ou no diretório definido por CODEX_HOME. O instalador usa um nome estável por vault, reaproveita entradas corretas e evita substituir servidores conflitantes. Antes de modificar um TOML existente, cria um backup config.toml.obsidian-mcp-backup-*; valores não relacionados são preservados, mas comentários e formatação podem ser normalizados.

Reinicie o Codex após configurar a conexão. Mantenha o vault aberto e o plugin ativo durante o uso.

Integração manual

Para instalar sem alterar a configuração do Codex:

obsidian-mcp install --vault "/caminho/do/vault" --manual

O CLI salva a tabela em .obsidian/plugins/obsidian-mcp/codex-config.toml, com permissão 0600 em Linux/macOS ou ACL privada no Windows. Essa alternativa também é gerada quando a configuração automática encontra um conflito ou um arquivo inacessível ou inválido.

Importe a tabela no TOML do Codex ou configure a conexão equivalente:

[mcp_servers.obsidian]
url = "http://127.0.0.1:27124/mcp"
http_headers = { Authorization = "Bearer COLE_AQUI_O_TOKEN_DE_DATA_JSON" }

Use a porta de data.json e evite duplicar uma tabela existente. O token é local, não uma chave da OpenAI. Não o publique em issues ou logs. A autenticação utiliza Bearer estático, sem OAuth. Se trocar a porta ou o token, atualize também a conexão do Codex; executar install novamente permite tentar reconciliar a integração.

Uso no Codex

Com as pastas do exemplo autorizadas, peça ao agente:

• “Liste minhas notas usando list_notes.”

• “Leia Notas/reuniao.md.”

• “Pesquise por ‘planejamento’ nas notas autorizadas.”

• “Crie Projetos/Compartilhados/rascunho.md com o conteúdo # Rascunho.”

As políticas de aprovação do cliente continuam valendo. Conteúdos retornados pelas ferramentas podem ser enviados pelo agente ao provedor de IA.

Ferramentas MCP

Os caminhos são relativos ao vault e incluem a pasta autorizada. Notas exigem extensão .md. As respostas incluem JSON no conteúdo textual MCP; falhas de execução retornam isError: true.

A busca é literal, ignora maiúsculas/minúsculas e pesquisa nos caminhos e conteúdos. Leitura, busca e criação de notas respeitam o limite de 1 MiB por nota em UTF-8; notas maiores ainda aparecem na listagem. Criações exigem uma pasta pai existente e não sobrescrevem arquivos. Não há ferramentas de edição ou exclusão de notas.

O transporte é Streamable HTTP sem sessões, via POST /mcp, com respostas JSON. Requisições com Origin são recusadas e o servidor valida o cabeçalho Host. A proteção de caminhos pressupõe um sistema de arquivos local confiável; ela não isola processos locais maliciosos que alterem arquivos durante uma operação.

Atualização e desinstalação

Atualizar

obsidian-mcp update --vault "/caminho/do/vault"

O comando reutiliza a origem registrada. Para fontes remotas, consulta latest novamente, salvo quando --version é informado. Para fontes locais, utiliza os artefatos do projeto registrado; compile a nova versão antes de atualizar. Downgrades são recusados.

A atualização preserva o conteúdo de data.json, incluindo token e allowedFolders, aplica 0600 em Linux/macOS ou ACL privada no Windows e mantém a escolha de ativação do plugin. Recarregue o plugin para executar a nova versão. O comando atualiza o plugin; o executável CLI deve ser obtido novamente quando houver uma nova versão dele.

Desinstalar

obsidian-mcp uninstall --vault "/caminho/do/vault"

Confirme digitando remover, ou use --yes em automações. O comando remove os arquivos conhecidos do plugin, seu token e a entrada de ativação. Notas e pastas do vault são mantidas. A entrada Codex criada pelo instalador é removida apenas se ainda corresponder à instalação; entradas manuais reaproveitadas ou alteradas são preservadas. Pastas do plugin com arquivos desconhecidos exigem revisão manual.

Feche e reabra o vault para descarregar uma instância ainda em memória.

Diagnóstico e solução de problemas

obsidian-mcp doctor --vault "/caminho/do/vault"

O diagnóstico verifica artefatos, configuração, permissões do token, registro de ativação, conexão HTTP, rejeição de chamadas sem token, autenticação MCP, versão carregada e integração local do Codex. Usa tools/list, sem ler ou criar notas.

Retorna 0 quando todas as verificações passam e 1 quando há falhas ou pendências. Install/update podem retornar 0 com a ativação ainda pendente; confira a mensagem final. Sem --vault, update/doctor/uninstall selecionam automaticamente uma única instalação descoberta; se houver várias, exigem seleção interativa ou caminho explícito.

Para erros de inicialização, abra o console de desenvolvedor do Obsidian e procure mensagens com [Obsidian MCP].

Desenvolvimento e contribuição

npm ci
npm test
npm run build

src/main.ts       Ciclo de vida do plugin
src/server/       Servidor HTTP e transporte MCP
src/tools/        Registro das ferramentas e schemas
src/vault/        Operações e políticas de acesso ao vault
src/settings.ts   Validação das configurações
cli/              Instalação, releases, integração Codex e diagnóstico
scripts/          Build e preparação de releases
install.sh        Bootstrap verificado para Linux/macOS
install.ps1       Bootstrap verificado para Windows
tests/            Testes do plugin e do CLI

Os testes usam vaults temporários e simulações da API Obsidian e de downloads. O workflow de testes está configurado para Linux, macOS e Windows, incluindo execução do instalador nativo com downloads simulados e verificações de ACL no Windows. Em ambientes que proíbem bind em localhost, os testes HTTP por socket são ignorados com aviso; execute-os em um ambiente sem essa restrição. Valide também o carregamento no Obsidian e a conexão no Codex antes de publicar uma release.

O estado da primeira publicação e as evidências disponíveis estão em Preparação da primeira release. Os resultados locais não substituem uma execução nativa da matriz do CI.

Para contribuir, descreva o comportamento esperado e o observado em uma issue. Em pull requests, mantenha as alterações focadas, inclua testes para mudanças de comportamento e informe as verificações executadas. Não inclua tokens nem conteúdo privado de vaults. Commits feitos por IA devem seguir AGENTS.md: título curto, corpo descritivo e trailer Co-authored-by: verificável, separados por linhas em branco.

O workflow de release depende da matriz nativa do workflow de testes e da verificação dos artefatos antes de publicar uma tag estável. A tag, com ou sem v, deve corresponder à versão de package.json e manifest.json. O estado do instalador fica em .installer.json na pasta do plugin e em installations.json no diretório de estado de cada sistema:

XDG_STATE_HOME, quando definido, substitui o diretório de estado em qualquer sistema. Instalações registradas no caminho antigo ~/.local/state/obsidian-mcp continuam sendo reconhecidas em macOS e Windows. A integração do Codex continua em ~/.codex/config.toml ou no diretório indicado por CODEX_HOME.

Os caminhos de perfil seguem os diretórios globais do Obsidian. No Windows, o CLI trata os launchers .cmd conforme o comportamento de processos filhos do Node.js.

Licença: BSD Zero Clause (0BSD).