Nix

An MCP server that exposes an Obsidian vault to development agents (Cursor, Claude Code, Copilot). Hybrid search, reading and writing notes — with local and free embeddings and vector database. The reasoning stays on the client; Nix only delivers tools.

Transport: MCP stdio. No subcommand — nix starts the server.

Why use

• The editor agent finds ideas, not just words: semantic + lexical search in the vault.

• Creates and updates notes in Obsidian format, without leaving Cursor.

• Everything runs on your machine. No piece of the vault goes to an embedding API.

• You control when the index changes: there's no background watcher.

Related MCP server: omega-obsidian

Requirements

• Python 3.11+ on the PATH

• An Obsidian vault (.md notes)

• ~2.3 GB free on the first sync (download of the BAAI/bge-m3 model)

Installation

There are two paths. Both create .venv, install the package, and run nix init (it asks for the vault path, or accepts --vault).

In your project (user)

1. Download the latest release (nix-x.y.z.zip).

2. Extract it at the workspace root and rename the folder to nix (the zip comes as nix-1.0.0/).

3. Run the installer inside that folder:

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"

On Windows, use slashes / in the vault path (C:/Obsidian/MeuVault). A backslash breaks the TOML.

Then register the server in the editor — see Registering in the MCP client. The installer writes NIX_HOME and puts nix on the PATH; when it finishes, it reports that the configuration is complete. Open a new terminal and run nix doctor / nix sync. If automatic registration fails, see INSTALL.md (section Registering NIX_HOME and the PATH manually). If the Nix package manager (NixOS) is already on the PATH, the installer warns: this nix takes priority.

From the repository (developer)

Clone the repository and run the same installer at the root:

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"

Manual installation (equivalent to the installer, with development dependencies):

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 and python -m nix are equivalent after the installer (in a new terminal) or after activating the venv. Cursor does not inherit the terminal's PATH — in MCP, always use the .venv Python.

Uninstall

In the Nix folder: uninstall.bat, .\uninstall.ps1, or bash uninstall.sh. Confirm with s, or pass --yes. This removes the PATH entry, .venv, the index (.nix/), and nix.toml. The vault is not deleted. --keep-data preserves the configuration and the index. Details: INSTALL.md.

Registering in the MCP client

The client starts the process. Reload the MCP servers after saving.

command must point to the wrapper inside the installation folder (NIX_HOME), not to the nix name on the PATH. The editor opened from the Dock or the menu does not inherit the terminal's PATH (spawn nix ENOENT). The path appears in nix doctor, in the comando nix: line.

Cursor — .cursor/mcp.json in the workspace:

Windows

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

On Windows, the IDE reads the NIX_HOME user variable. An absolute path also works, e.g. C:/Users/voce/nix/bin/nix.cmd.

macOS / Linux

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

Replace /Users/voce/nix with the installation folder. "command": "nix" fails in the IDE. bin/nix.cmd closes the connection with EACCES. ${env:NIX_HOME} generally does not expand: the app doesn't read .zshrc / .bashrc.

The same pattern applies to Claude Code and Copilot. stdout belongs to the MCP protocol: logs only go to .nix/logs/nix.log in the Nix folder.

Getting started

After init (the installer already runs it), open a new terminal and run:

nix doctor
nix sync
nix status

If nix is not found, the terminal still has the old PATH: close it and open another one.

Registering NIX_HOME and the PATH manually

If the installer doesn't write the variables, the step-by-step is only in INSTALL.md (the release zip includes that file). Write what's missing and open a new terminal.

The first sync (or any operation that embeds) downloads the BAAI/bge-m3 model (~2.3 GB) from Hugging Face. On subsequent runs, only what changed is reprocessed.

New notes without a folder in the path go to vault.default_new_note_folder (default Inbox).

Indexing

This is the central rule:

Changes made outside Nix (Obsidian, editor) are not indexed on their own. Changes made by the MCP tools update the index in the same operation.

After editing in Obsidian, run nix sync or ask the agent for sync_index. If vectorization of a write fails, the file remains in the vault (source of truth) and a nix sync fixes the index.

CLI

MCP tools

Twelve tools, defined in src/nix/core/tools/registry.py. Notes also appear as the resource nix://note/{+rel_path}.

Configuration

File (first one found): $NIX_CONFIG (if set, only it) → nix.toml in the Nix folder ($NIX_HOME or the checkout) → nix.toml in the CWD and its parents (last resort). Relative paths resolve against the directory of the TOML file. NIX_SECAO__CAMPO variables override the file (e.g., NIX_VAULT__PATH). nix init writes to that same path.

Useful settings in the TOML generated by init:

Publishing a release

A GitHub release is created automatically when a vX.Y.Z tag reaches the remote. The .github/workflows/release.yml workflow verifies the version, runs ruff and mypy, builds nix-x.y.z.zip, and publishes to Releases.

1. Update [project].version in pyproject.toml (e.g., 1.0.2). The tag must match that value — otherwise the job fails.

2. Commit and push to the main branch.

3. Create and push the tag (the v prefix is required):

git tag v1.1.3
git push origin v1.1.3

4. Follow the Release workflow in Actions. If successful, the Nix v1.0.2 release appears with the zip and the .sha256 checksum.

To republish the artifacts of an existing tag, trigger the workflow manually: Actions → Release → Run workflow, and provide the tag (e.g., v1.0.2).

Documentation

• PRD.md — product, requirements, and business rules

• ARCHITECTURE.md — components, indexing, retrieval, and MCP stdio