Nix

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

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 Ihrem Rechner. Kein Teil des Vaults geht an eine Embedding-API.

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

Anforderungen

• 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 letzte Version herunter (nix-x.y.z.zip).

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

3. Führen Sie das Installationsprogramm in diesem Ordner aus:

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"

Unter Windows verwenden Sie Schrägstriche / im Vault-Pfad (C:/Users/voce/Vault). Ein umgekehrter Schrägstrich bricht das TOML.

Registrieren Sie dann den Server im Editor – siehe Registrierung im MCP-Client.

Aus dem Repository (Entwickler)

Klonen Sie das Repository und führen Sie das gleiche Installationsprogramm im Root aus:

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

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

Manuelle Installation (entspricht dem Installationsprogramm, 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:/Users/voce/Vault"

nix und python -m nix sind nach der Aktivierung des venv äquivalent. Cursor erbt das PATH des Terminals nicht – verwenden Sie im MCP immer das Python aus .venv.

Registrierung im MCP-Client

Der Client startet den Prozess. Die IDE erbt nicht das PATH des Terminals: Der Befehl nix aus dem venv wird nicht gefunden und die Verbindung schließt ('nix' wird nicht erkannt).

Zeigen Sie auf das Python der virtuellen Umgebung. Laden Sie die MCP-Server nach dem Speichern neu.

Cursor – .cursor/mcp.json im Workspace:

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

Passen Sie command je nach Fall an:

Das gleiche Muster (Pfad/zum/python + ["-m", "nix"]) gilt für Claude Code und Copilot. stdout gehört zum MCP-Protokoll: Logs nur in ~/.nix/logs/nix.log.

Erste Schritte

Nach dem init (das Installationsprogramm startet dies bereits):

# 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

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 erneut verarbeitet.

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

Indizierung

Dies ist die zentrale Regel:

Änderungen, die außerhalb von Nix (Obsidian, Editor) vorgenommen werden, werden nicht automatisch indiziert. Änderungen durch die MCP-Werkzeuge aktualisieren den Index im selben Vorgang.

Nach dem Bearbeiten in Obsidian führen Sie nix sync aus oder bitten Sie 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-Werkzeuge

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

Konfiguration

Datei (erste gefundene): $NIX_CONFIG → ./nix.toml → ~/.nix/config.toml. Variablen NIX_SECAO__CAMPO überschreiben die Datei (z. B. NIX_VAULT__PATH).

Nützliche Punkte des von init generierten TOML:

Dokumentation

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

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