Nix

Servidor MCP que expõe um vault do Obsidian a agentes de desenvolvimento (Cursor, Claude Code, Copilot). Busca híbrida, leitura e escrita nas notas — com embeddings e banco vetorial locais e gratuitos. O raciocínio fica no cliente; o Nix só entrega ferramentas.

Transporte: MCP stdio. Sem subcomando, nix inicia o servidor.

Por que usar

• O agente do editor encontra ideias, não só palavras: busca semântica + léxica no vault.

• Cria e atualiza notas no formato do Obsidian, sem sair do Cursor.

• Tudo roda na sua máquina. Nenhum trecho do vault vai para API de embedding.

• Você controla quando o índice muda: não há watcher em segundo plano.

Related MCP server: Obsidian MCP Server

Requisitos

• Python 3.11+ no PATH (incluindo 3.14; o CI e o mypy usam 3.14)

• Um vault do Obsidian (notas .md)

Instalação

Há dois caminhos. Os dois criam .venv, instalam o pacote e disparam nix init (pergunta o caminho do vault, ou aceite --vault).

No seu projeto (usuário)

1. Baixe a última release (nix-x.y.z.zip).

2. Extraia na raiz do workspace e renomeie a pasta para nix (o zip vem como nix-1.0.0/).

3. Rode o instalador dentro dessa pasta:

cd nix
install.bat
:: ou, se já souber o vault:
install.bat --vault "C:/Obsidian/MeuVault"

cd nix
.\install.ps1
# ou: .\install.ps1 --vault "C:/Obsidian/MeuVault"

cd nix
bash install.sh
# ou: bash install.sh --vault "$HOME/Vault"

No Windows use barras / no caminho do vault (C:/Obsidian/MeuVault). Barra invertida quebra o TOML.

Depois registre o servidor no editor — veja Registro no cliente MCP. O instalador grava NIX_HOME e coloca nix no PATH; ao terminar, informa que a configuração foi concluída. Abra um novo terminal e rode nix doctor / nix sync. Se o registro automático falhar, veja INSTALL.md (seção Registrar NIX_HOME e o PATH à mão). Se o gerenciador Nix (NixOS) já estiver no PATH, o instalador avisa: este nix passa a ter prioridade.

A partir do repositório (desenvolvedor)

Clone o repositório e rode o mesmo instalador na raiz:

install.bat
:: ou: install.bat --vault "C:/Obsidian/MeuVault"

bash install.sh
# ou: bash install.sh --vault "$HOME/Vault"

.\install.ps1
# ou: .\install.ps1 --vault "C:/Obsidian/MeuVault"

Instalação manual (equivale ao instalador, com dependências de desenvolvimento):

python -m venv .venv
# Windows (Git Bash): source .venv/Scripts/activate
# Linux/macOS:        source .venv/bin/activate

pip install -r requirements-dev.txt
pip install -e .
python -m nix init                # ou: python -m nix init --vault "C:/Obsidian/MeuVault"

nix e python -m nix são equivalentes depois do instalador (num terminal novo) ou de ativar o venv. O Cursor não herda o PATH do terminal — no MCP use sempre o Python do .venv.

Desinstalar

Na pasta do Nix: uninstall.bat, .\uninstall.ps1 ou bash uninstall.sh. Confirme com s, ou passe --yes. Isso remove o PATH, o .venv, o índice (.nix/) e o nix.toml. O vault não é apagado. --keep-data preserva a configuração e o índice. Detalhes: INSTALL.md.

Registro no cliente MCP

O cliente inicia o processo. Recarregue os servidores MCP depois de salvar.

command deve apontar para o wrapper dentro da pasta da instalação (NIX_HOME), não para o nome nix no PATH. O editor aberto pelo Dock ou pelo menu não herda o PATH do terminal (spawn nix ENOENT). O caminho aparece em nix doctor, na linha comando nix:.

Cursor — .cursor/mcp.json no workspace:

Windows

{
  "mcpServers": {
    "nix": {
      "command": "${env:NIX_HOME}/bin/nix.cmd"
    }
  }
}

No Windows a IDE lê a variável de usuário NIX_HOME. Também vale o caminho absoluto, por exemplo C:/Users/voce/nix/bin/nix.cmd.

macOS / Linux

{
  "mcpServers": {
    "nix": {
      "command": "/Users/voce/nix/bin/nix"
    }
  }
}

Troque /Users/voce/nix pela pasta da instalação. "command": "nix" falha na IDE. bin/nix.cmd fecha a conexão com EACCES. ${env:NIX_HOME} em geral não expande: o app não lê .zshrc / .bashrc.

O mesmo padrão vale para Claude Code e Copilot. stdout é do protocolo MCP: logs só em .nix/logs/nix.log na pasta do Nix.

Primeiros passos

Depois do init (o instalador já dispara isso), abra um novo terminal e rode:

nix doctor
nix sync
nix status

Se nix não for encontrado, o terminal ainda tem o PATH antigo: feche-o e abra outro.

Registrar NIX_HOME e o PATH à mão

Se o instalador não gravar as variáveis, o passo a passo está só no INSTALL.md (o zip da release inclui esse arquivo). Grave o que faltou e abra um terminal novo.

O primeiro sync (ou qualquer operação que embede) baixa o modelo configurado. O padrão BAAI/bge-m3 pesa ~2,3 GB. Não precisa de GPU, mas na CPU a primeira carga e cada nota podem levar muitos minutos — a barra só avança ao terminar o arquivo. Em máquina fraca com português, use sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 (~220 MB) e rode nix sync --full. O nix init lista a comparação.

Notas novas sem pasta no caminho vão para vault.default_new_note_folder (padrão Inbox).

Indexação

Esta é a regra central:

Alterações feitas fora do Nix (Obsidian, editor) não são indexadas sozinhas. Alterações feitas pelas ferramentas MCP atualizam o índice na mesma operação.

Depois de editar no Obsidian, rode nix sync ou peça sync_index ao agente. Se a vetorização de uma escrita falhar, o arquivo permanece no vault (fonte da verdade) e um nix sync corrige o índice.

CLI

Ferramentas MCP

Doze ferramentas, definidas em src/nix/core/tools/registry.py. Notas também aparecem como recurso nix://note/{+rel_path}.

Configuração

Arquivo (primeiro encontrado): $NIX_CONFIG (se definido, só ele) → nix.toml na pasta do Nix ($NIX_HOME ou o checkout) → nix.toml no CWD e nos pais (último recurso). Caminhos relativos resolvem contra o diretório do TOML. Variáveis NIX_SECAO__CAMPO sobrescrevem o arquivo (ex.: NIX_VAULT__PATH). nix init grava nesse mesmo caminho.

Pontos úteis do TOML gerado pelo init:

Publicar uma versão

Uma release no GitHub é criada automaticamente quando uma tag vX.Y.Z chega no remoto. O workflow .github/workflows/release.yml confere a versão, roda ruff e mypy, monta nix-x.y.z.zip e publica em Releases.

1. Atualize [project].version em pyproject.toml (ex.: 1.0.2). A tag precisa bater com esse valor — senão o job falha.

2. Faça o commit e o push na branch principal.

3. Crie e envie a tag (o v no prefixo é obrigatório):

git tag v1.1.3
git push origin v1.1.3

4. Acompanhe o workflow Release em Actions. Em caso de sucesso, a release Nix v1.0.2 aparece com o zip e o checksum .sha256.

Para republicar os artefatos de uma tag que já existe, dispare o workflow à mão: Actions → Release → Run workflow, e informe a tag (ex.: v1.0.2).

Documentação

• PRD.md — produto, requisitos e regras de negócio

• ARCHITECTURE.md — componentes, indexação, recuperação e MCP stdio