Nix

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

Transport: MCP stdio. With no subcommand, nix starts the server.

Why use it

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

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

• Everything runs on your machine. No vault snippet goes to an embedding API.

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

Requirements

• Python 3.11+ on the PATH

• An Obsidian vault (.md notes)

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

Installation

There are two paths. Both create .venv, install the package, and trigger nix init (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 root of the workspace 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:/Users/voce/Vault"

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

On Windows use forward slashes / in the vault path (C:/Users/you/Vault). A backslash breaks the TOML.

Then register the server in the editor — see MCP client registration.

From the repository (developer)

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

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

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

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

nix and python -m nix are equivalent after activating the venv. Cursor does not inherit the terminal's PATH — in MCP always use the Python from .venv.

MCP client registration

The client starts the process. The IDE does not inherit the terminal's PATH: the nix command from the venv is not found and the connection closes ('nix' is not recognized).

Point to the virtual environment's Python. Reload the MCP servers after saving.

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

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

Adjust command as needed:

The same pattern (path/to/python + ["-m", "nix"]) applies to Claude Code and Copilot. stdout is the MCP protocol: logs only in ~/.nix/logs/nix.log.

Getting started

After init (the installer already triggers this):

# 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

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 nix://note/{+rel_path} resource.

Configuration

File (first found): $NIX_CONFIG → ./nix.toml → ~/.nix/config.toml. NIX_SECTION__FIELD variables override the file (e.g.: NIX_VAULT__PATH).

Useful points of the TOML generated by init:

Documentation

• PRD.md — product, requirements and business rules

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