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 banco 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é usar

• 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.

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:/Users/voce/Vault"

cd nix
chmod +x setup.sh
./setup.sh
# ou: ./setup.sh --vault "$HOME/Vault"

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

Después registra el servidor en el editor — ver Registro en el cliente MCP.

Desde el repositorio (desarrollador)

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

setup.bat
:: ou: setup.bat --vault "C:/Users/voce/Vault"

chmod +x setup.sh
./setup.sh
# ou: ./setup.sh --vault "$HOME/Vault"

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:/Users/voce/Vault"

nix y python -m nix son equivalentes después de activar el venv. Cursor no hereda el PATH del terminal — en MCP usa siempre el Python del .venv.

Registro en el cliente MCP

El cliente inicia el proceso. La IDE no hereda el PATH del terminal: el comando nix del venv no se encuentra y la conexión se cierra ('nix' no es reconocido).

Apunta al Python del entorno virtual. Recarga los servidores MCP después de guardar.

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

{
  "mcpServers": {
    "nix": {
      "command": "${workspaceFolder}/nix/.venv/Scripts/python.exe",
      "args": ["-m", "nix"]
    }
  }
}

Ajusta command según el caso:

El mismo patrón (caminho/do/python + ["-m", "nix"]) vale para Claude Code y Copilot. stdout es del protocolo MCP: logs solo en ~/.nix/logs/nix.log.

Primeros pasos

Después del init (el instalador ya lo dispara):

# Windows
.venv\Scripts\python.exe -m nix doctor
.venv\Scripts\python.exe -m nix sync
.venv\Scripts\python.exe -m nix status

# Linux / macOS
.venv/bin/python -m nix doctor
.venv/bin/python -m nix sync
.venv/bin/python -m nix status

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.

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

Indexación

Esta es la regla central:

Los cambios hechos fuera de Nix (Obsidian, editor) no se indexan solos. Los 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 → ./nix.toml → ~/.nix/config.toml. Las variables NIX_SECAO__CAMPO sobrescriben el archivo (ej.: NIX_VAULT__PATH).

Puntos útiles del TOML generado por init:

Documentación

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

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