Nix

MCP-Server, der ein Obsidian-Vault für Entwicklungsagenten (Cursor, Claude Code, Copilot) bereitstellt. Hybride Suche, Lesen und Schreiben in den Notizen – mit lokalen und kostenlosen Embeddings und Vektordatenbank. Das Denken bleibt im Client; Nix liefert nur Tools.

Transport: MCP stdio. Ohne Unterbefehl startet nix den Server.

Warum verwenden

• Der Editor-Agent findet Ideen, nicht nur Wörter: semantische + lexikalische Suche im Vault.

• Erstellt und aktualisiert Notizen im Obsidian-Format, ohne Cursor zu verlassen.

• Alles läuft auf Ihrer Maschine. Kein Teil des Vaults geht an eine Embedding-API.

• Sie kontrollieren, wann sich der Index ändert: Es gibt keinen Watcher im Hintergrund.

Related MCP server: Obsidian MCP Server

Voraussetzungen

• Python 3.11+ im PATH

• Ein Obsidian-Vault (.md-Notizen)

• ~2,3 GB freier Speicherplatz bei der ersten Synchronisierung (Download des Modells BAAI/bge-m3)

Installation

Es gibt zwei Wege. Beide erstellen .venv, installieren das Paket und starten nix init (fragt nach dem Vault-Pfad oder akzeptiert --vault).

In Ihrem Projekt (Benutzer)

1. Laden Sie die neueste Version herunter (nix-x.y.z.zip).

2. Entpacken Sie im Workspace-Root und benennen Sie den Ordner in nix um (das Zip kommt als nix-1.0.0/).

3. Führen Sie den Installer in diesem Ordner aus:

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"

Unter Windows verwenden Sie Schrägstriche / für den Vault-Pfad (C:/Obsidian/MeuVault). Ein umgekehrter Schrägstrich bricht das TOML.

Danach registrieren Sie den Server im Editor – siehe Registrierung im MCP-Client. Der Installer schreibt NIX_HOME und setzt nix in den PATH; am Ende meldet er, dass die Konfiguration abgeschlossen ist. Öffnen Sie ein neues Terminal und führen Sie nix doctor / nix sync aus. Wenn die automatische Registrierung fehlschlägt, siehe INSTALL.md (Abschnitt NIX_HOME und PATH von Hand registrieren). Wenn der Nix-Manager (NixOS) bereits im PATH ist, warnt der Installer: Dieses nix hat dann Vorrang.

Aus dem Repository (Entwickler)

Klonen Sie das Repository und führen Sie denselben Installer im Root aus:

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"

Manuelle Installation (entspricht dem Installer, mit Entwicklungsabhängigkeiten):

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 und python -m nix sind nach dem Installer (in einem neuen Terminal) oder nach Aktivierung des venv gleichwertig. Cursor erbt den PATH des Terminals nicht – verwenden Sie im MCP immer das Python aus .venv.

Deinstallieren

Im Nix-Ordner: uninstall.bat, .\uninstall.ps1 oder bash uninstall.sh. Bestätigen Sie mit s oder übergeben Sie --yes. Dies entfernt den PATH, das .venv, den Index (.nix/) und die nix.toml. Das Vault wird nicht gelöscht. --keep-data erhält die Konfiguration und den Index. Details: INSTALL.md.

Registrierung im MCP-Client

Der Client startet den Prozess. Laden Sie die MCP-Server nach dem Speichern neu.

command muss auf den Wrapper im Installationsordner (NIX_HOME) zeigen, nicht auf den Namen nix im PATH. Der über das Dock oder das Menü geöffnete Editor erbt den PATH des Terminals nicht (spawn nix ENOENT). Der Pfad erscheint in nix doctor in der Zeile comando nix:.

Cursor – .cursor/mcp.json im Workspace:

Windows

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

Unter Windows liest die IDE die Benutzervariable NIX_HOME. Auch der absolute Pfad funktioniert, z. B. C:/Users/voce/nix/bin/nix.cmd.

macOS / Linux

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

Ersetzen Sie /Users/voce/nix durch den Installationsordner. "command": "nix" schlägt in der IDE fehl. bin/nix.cmd schließt die Verbindung mit EACCES. ${env:NIX_HOME} wird in der Regel nicht expandiert: Die App liest .zshrc / .bashrc nicht.

Dasselbe Muster gilt für Claude Code und Copilot. stdout gehört zum MCP-Protokoll: Logs nur in .nix/logs/nix.log im Nix-Ordner.

Erste Schritte

Nach dem init (der Installer startet dies bereits), öffnen Sie ein neues Terminal und führen Sie aus:

nix doctor
nix sync
nix status

Wenn nix nicht gefunden wird, hat das Terminal noch den alten PATH: Schließen Sie es und öffnen Sie ein neues.

NIX_HOME und PATH von Hand registrieren

Wenn der Installer die Variablen nicht speichert, finden Sie die Schritt-für-Schritt-Anleitung nur in INSTALL.md (das Release-Zip enthält diese Datei). Speichern Sie, was fehlt, und öffnen Sie ein neues Terminal.

Die erste sync (oder jede Operation, die einbettet) lädt das Modell BAAI/bge-m3 (~2,3 GB) von Hugging Face herunter. Bei den folgenden wird nur das Geänderte neu verarbeitet.

Neue Notizen ohne Ordner im Pfad gehen an vault.default_new_note_folder (Standard Inbox).

Indexierung

Dies ist die zentrale Regel:

Änderungen, die außerhalb von Nix vorgenommen werden (Obsidian, Editor), werden nicht automatisch indiziert. Änderungen durch die MCP-Tools aktualisieren den Index in derselben Operation.

Nach dem Bearbeiten im Obsidian führen Sie nix sync aus oder bitten den Agenten um sync_index. Wenn die Vektorisierung eines Schreibvorgangs fehlschlägt, bleibt die Datei im Vault (Quelle der Wahrheit) und ein nix sync korrigiert den Index.

CLI

MCP-Tools

Zwölf Tools, definiert in src/nix/core/tools/registry.py. Notizen erscheinen auch als Ressource nix://note/{+rel_path}.

Konfiguration

Datei (erste gefundene): $NIX_CONFIG (falls definiert, nur diese) → nix.toml im Nix-Ordner ($NIX_HOME oder das Checkout) → nix.toml im CWD und in den übergeordneten Verzeichnissen (letzter Ausweg). Relative Pfade werden relativ zum TOML-Verzeichnis aufgelöst. Variablen NIX_SECAO__CAMPO überschreiben die Datei (z. B. NIX_VAULT__PATH). nix init schreibt in denselben Pfad.

Nützliche Punkte des vom init generierten TOML:

Eine Version veröffentlichen

Eine GitHub-Release wird automatisch erstellt, wenn ein Tag vX.Y.Z im Remote ankommt. Der Workflow .github/workflows/release.yml prüft die Version, führt ruff und mypy aus, erstellt nix-x.y.z.zip und veröffentlicht es unter Releases.

1. Aktualisieren Sie [project].version in pyproject.toml (z. B. 1.0.2). Der Tag muss mit diesem Wert übereinstimmen – sonst schlägt der Job fehl.

2. Committen und pushen Sie auf den Hauptbranch.

3. Erstellen und senden Sie den Tag (das v im Präfix ist erforderlich):

git tag v1.1.3
git push origin v1.1.3

4. Verfolgen Sie den Workflow Release in Actions. Bei Erfolg erscheint die Release Nix v1.0.2 mit dem Zip und der Prüfsumme .sha256.

Um die Artefakte eines bereits vorhandenen Tags erneut zu veröffentlichen, starten Sie den Workflow manuell: Actions → Release → Run workflow, und geben Sie den Tag an (z. B. v1.0.2).

Dokumentation

• PRD.md – Produkt, Anforderungen und Geschäftsregeln

• ARCHITECTURE.md – Komponenten, Indexierung, Abruf und MCP stdio