Nix

一个 MCP 服务器，将 Obsidian 仓库暴露给开发代理（Cursor、Claude Code、Copilot）。混合搜索、读写笔记——使用本地且免费的嵌入和向量数据库。推理在客户端进行；Nix 只提供工具。

传输方式：MCP stdio。无子命令，nix 启动服务器。

为什么使用

• 编辑器代理找到想法，而不仅仅是词语：仓库中的语义 + 词法搜索。

• 创建和更新 Obsidian 格式的笔记，无需离开 Cursor。

• 一切都在您的机器上运行。仓库的任何片段都不会发送到嵌入 API。

• 您控制索引何时更改：没有后台监视器。

Related MCP server: Obsidian MCP Server

要求

• PATH 中的 Python 3.11+

• 一个 Obsidian 仓库（.md 笔记）

• 首次同步时约需 2.3 GB 可用空间（下载 BAAI/bge-m3 模型）

安装

有两种方式。两者都会创建 .venv、安装包并触发 nix init（询问仓库路径，或接受 --vault）。

在您的项目中（用户）

1. 下载最新版本（nix-x.y.z.zip）。

2. 解压到工作区根目录并将文件夹重命名为 nix（zip 以 nix-1.0.0/ 形式提供）。

3. 在该文件夹内运行安装程序：

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"

在 Windows 上，仓库路径使用 / 斜杠（C:/Obsidian/MeuVault）。反斜杠会破坏 TOML。

然后在编辑器中注册服务器——参见 在 MCP 客户端中注册。安装程序会写入 NIX_HOME 并将 nix 添加到 PATH；完成后，会告知配置已完成。打开一个新终端并运行 nix doctor / nix sync。如果自动注册失败，请参阅 INSTALL.md（手动注册 NIX_HOME 和 PATH 部分）。如果 Nix 管理器（NixOS）已在 PATH 中，安装程序会警告：此 nix 将具有优先权。

从仓库（开发者）

克隆仓库并在根目录运行相同的安装程序：

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"

手动安装（等同于安装程序，包含开发依赖）：

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"

安装程序后（在新终端中）或激活 venv 后，nix 和 python -m nix 是等效的。Cursor 不会继承终端的 PATH——在 MCP 中始终使用 .venv 中的 Python。

卸载

在 Nix 文件夹中：uninstall.bat、.\uninstall.ps1 或 bash uninstall.sh。用 s 确认，或传递 --yes。这会移除 PATH、.venv、索引（.nix/）和 nix.toml。仓库不会被删除。--keep-data 保留配置和索引。详情：INSTALL.md。

在 MCP 客户端中注册

客户端启动进程。保存后重新加载 MCP 服务器。

command 必须指向安装文件夹内的包装器（NIX_HOME），而不是 PATH 中的 nix 名称。通过 Dock 或菜单打开的编辑器不会继承终端的 PATH（spawn nix ENOENT）。该路径出现在 nix doctor 的 comando nix: 行中。

Cursor — 工作区中的 .cursor/mcp.json：

Windows

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

在 Windows 上，IDE 读取用户变量 NIX_HOME。绝对路径也有效，例如 C:/Users/voce/nix/bin/nix.cmd。

macOS / Linux

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

将 /Users/voce/nix 替换为安装文件夹。"command": "nix" 在 IDE 中会失败。bin/nix.cmd 会以 EACCES 关闭连接。${env:NIX_HOME} 通常不会展开：应用不读取 .zshrc / .bashrc。

同样的模式适用于 Claude Code 和 Copilot。stdout 是 MCP 协议：日志仅在 Nix 文件夹中的 .nix/logs/nix.log。

快速开始

在 init（安装程序已触发）之后，打开一个新终端并运行：

nix doctor
nix sync
nix status

如果找不到 nix，终端仍具有旧 PATH：关闭并重新打开一个。

手动注册 NIX_HOME 和 PATH

如果安装程序未写入变量，步骤仅在 INSTALL.md 中（release zip 包含该文件）。写入缺失的部分并打开新终端。

第一次 sync（或任何嵌入操作）会从 Hugging Face 下载 BAAI/bge-m3 模型（约 2.3 GB）。后续仅重新处理更改的内容。

路径中没有文件夹的新笔记将进入 vault.default_new_note_folder（默认 Inbox）。

索引

这是核心规则：

在 Nix 外部（Obsidian、编辑器）所做的更改不会自动索引。由 MCP 工具所做的更改会在同一操作中更新索引。

在 Obsidian 中编辑后，运行 nix sync 或要求代理执行 sync_index。如果写入的向量化失败，文件仍保留在仓库中（事实来源），nix sync 会修复索引。

CLI

MCP 工具

十二个工具，定义在 src/nix/core/tools/registry.py 中。笔记也可作为资源 nix://note/{+rel_path} 出现。

配置

文件（第一个找到的）：$NIX_CONFIG（如果定义，仅此文件）→ Nix 文件夹中的 nix.toml（$NIX_HOME 或 checkout）→ CWD 及其父目录中的 nix.toml（最后手段）。相对路径相对于 TOML 目录解析。NIX_SECAO__CAMPO 变量覆盖文件（例如：NIX_VAULT__PATH）。nix init 写入同一路径。

init 生成的 TOML 中有用的点：

发布版本

当 vX.Y.Z 标签到达远程时，GitHub release 会自动创建。工作流 .github/workflows/release.yml 检查版本、运行 ruff 和 mypy、构建 nix-x.y.z.zip 并发布到 Releases。

1. 更新 pyproject.toml 中的 [project].version（例如：1.0.2）。标签必须与此值匹配——否则作业失败。

2. 提交并推送到主分支。

3. 创建并推送标签（v 前缀是必需的）：

git tag v1.1.3
git push origin v1.1.3

4. 在 Actions 中跟踪 Release 工作流。成功后，release Nix v1.0.2 会显示 zip 和校验和 .sha256。

要重新发布已存在标签的工件，请手动触发工作流：Actions → Release → Run workflow，并指定标签（例如：v1.0.2）。

文档

• PRD.md — 产品、需求和业务规则

• ARCHITECTURE.md — 组件、索引、检索和 MCP stdio