Nix

Servidor MCP que expone un vault de Obsidian a agentes de desarrollo (Cursor, Claude Code, Copilot). Búsqueda híbrida, lectura y escritura en las notas — con embeddings y base vectorial locales y gratuitos. El razonamiento queda en el cliente; Nix solo entrega herramientas.

Transporte: MCP stdio. Sin subcomando, nix inicia el servidor.

Por qué usarlo

• El agente del editor encuentra ideas, no solo palabras: búsqueda semántica + léxica en el vault.

• Crea y actualiza notas en el formato de Obsidian, sin salir de Cursor.

• Todo corre en tu máquina. Ningún fragmento del vault va a una API de embedding.

• Tú controlas cuándo cambia el índice: no hay watcher en segundo plano.

Related MCP server: Obsidian MCP Server

Requisitos

• Python 3.11+ en el PATH

• Un vault de Obsidian (notas .md)

• ~2,3 GB libres en la primera sincronización (descarga del modelo BAAI/bge-m3)

Instalación

Hay dos caminos. Ambos crean .venv, instalan el paquete y disparan nix init (pregunta la ruta del vault, o acepta --vault).

En tu proyecto (usuario)

1. Descarga la última release (nix-x.y.z.zip).

2. Extrae en la raíz del workspace y renombra la carpeta a nix (el zip viene como nix-1.0.0/).

3. Ejecuta el instalador dentro de esa carpeta:

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

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

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

En Windows usa barras / en la ruta del vault (C:/Obsidian/MiVault). La barra invertida rompe el TOML.

Después registra el servidor en el editor — ver Registro en el cliente MCP. El instalador graba NIX_HOME y coloca nix en el PATH; al terminar, informa que la configuración se completó. Abre una terminal nueva y ejecuta nix doctor / nix sync. Si el registro automático falla, ver INSTALL.md (sección Registrar NIX_HOME y el PATH a mano). Si el gestor Nix (NixOS) ya está en el PATH, el instalador avisa: este nix pasa a tener prioridad.

Desde el repositorio (desarrollador)

Clona el repositorio y ejecuta el mismo instalador en la raíz:

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

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

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

Instalación manual (equivale al instalador, con dependencias de desarrollo):

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 y python -m nix son equivalentes después del instalador (en una terminal nueva) o de activar el venv. Cursor no hereda el PATH de la terminal — en el MCP usa siempre el Python del .venv.

Desinstalar

En la carpeta de Nix: uninstall.bat, .\uninstall.ps1 o bash uninstall.sh. Confirma con s, o pasa --yes. Esto elimina el PATH, el .venv, el índice (.nix/) y el nix.toml. El vault no se borra. --keep-data conserva la configuración y el índice. Detalles: INSTALL.md.

Registro en el cliente MCP

El cliente inicia el proceso. Recarga los servidores MCP después de guardar.

command debe apuntar al wrapper dentro de la carpeta de instalación (NIX_HOME), no al nombre nix en el PATH. El editor abierto desde el Dock o desde el menú no hereda el PATH de la terminal (spawn nix ENOENT). La ruta aparece en nix doctor, en la línea comando nix:.

Cursor — .cursor/mcp.json en el workspace:

Windows

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

En Windows la IDE lee la variable de usuario NIX_HOME. También vale la ruta absoluta, por ejemplo C:/Users/tu/nix/bin/nix.cmd.

macOS / Linux

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

Cambia /Users/tu/nix por la carpeta de instalación. "command": "nix" falla en la IDE. bin/nix.cmd cierra la conexión con EACCES. ${env:NIX_HOME} en general no expande: la app no lee .zshrc / .bashrc.

El mismo patrón vale para Claude Code y Copilot. stdout es del protocolo MCP: logs solo en .nix/logs/nix.log en la carpeta de Nix.

Primeros pasos

Después del init (el instalador ya lo dispara), abre una terminal nueva y ejecuta:

nix doctor
nix sync
nix status

Si nix no se encuentra, la terminal aún tiene el PATH antiguo: ciérrala y abre otra.

Registrar NIX_HOME y el PATH a mano

Si el instalador no graba las variables, el paso a paso está solo en INSTALL.md (el zip de la release incluye ese archivo). Graba lo que falte y abre una terminal nueva.

El primer sync (o cualquier operación que embeba) descarga el modelo BAAI/bge-m3 (~2,3 GB) de Hugging Face. En las siguientes, solo lo que cambió se reprocesa.

Notas nuevas sin carpeta en la ruta van a vault.default_new_note_folder (por defecto Inbox).

Indexación

Esta es la regla central:

Cambios hechos fuera de Nix (Obsidian, editor) no se indexan solos. Cambios hechos por las herramientas MCP actualizan el índice en la misma operación.

Después de editar en Obsidian, ejecuta nix sync o pide sync_index al agente. Si la vectorización de una escritura falla, el archivo permanece en el vault (fuente de la verdad) y un nix sync corrige el índice.

CLI

Herramientas MCP

Doce herramientas, definidas en src/nix/core/tools/registry.py. Las notas también aparecen como recurso nix://note/{+rel_path}.

Configuración

Archivo (primero encontrado): $NIX_CONFIG (si está definido, solo él) → nix.toml en la carpeta de Nix ($NIX_HOME o el checkout) → nix.toml en el CWD y en los padres (último recurso). Las rutas relativas se resuelven contra el directorio del TOML. Variables NIX_SECCION__CAMPO sobrescriben el archivo (ej.: NIX_VAULT__PATH). nix init graba en esa misma ruta.

Puntos útiles del TOML generado por init:

Publicar una versión

Una release en GitHub se crea automáticamente cuando una tag vX.Y.Z llega al remoto. El workflow .github/workflows/release.yml verifica la versión, ejecuta ruff y mypy, arma nix-x.y.z.zip y publica en Releases.

1. Actualiza [project].version en pyproject.toml (ej.: 1.0.2). La tag debe coincidir con ese valor — si no, el job falla.

2. Haz el commit y el push en la rama principal.

3. Crea y envía la tag (el v en el prefijo es obligatorio):

git tag v1.1.3
git push origin v1.1.3

4. Sigue el workflow Release en Actions. En caso de éxito, la release Nix v1.0.2 aparece con el zip y el checksum .sha256.

Para republicar los artefactos de una tag que ya existe, dispara el workflow a mano: Actions → Release → Run workflow, e indica la tag (ej.: v1.0.2).

Documentación

• PRD.md — producto, requisitos y reglas de negocio

• ARCHITECTURE.md — componentes, indexación, recuperación y MCP stdio