Nix

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

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

为什么使用

• 编辑器代理找到想法，而不仅仅是词语：在 vault 中进行语义 + 词法搜索。

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

• 一切都在你的机器上运行。vault 的任何内容都不会发送到嵌入 API。

• 你控制索引何时更新：没有后台 watcher。

要求

• PATH 中有 Python 3.11+

• 一个 Obsidian vault（.md 笔记）

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

安装

有两种方式。两者都会创建 .venv、安装包并触发 nix init（询问 vault 路径，或接受 --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:/Users/voce/Vault"

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

在 Windows 上，vault 路径使用正斜杠 /（C:/Users/voce/Vault）。反斜杠会破坏 TOML。

然后在编辑器中注册服务器——参见 MCP 客户端注册。

从仓库（开发者）

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

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

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

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

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 和 python -m nix 在激活 venv 之后是等价的。Cursor 不会继承终端的 PATH——在 MCP 中始终使用 .venv 中的 Python。

MCP 客户端注册

客户端启动进程。IDE 不会继承终端的 PATH：找不到 venv 中的 nix 命令，连接会关闭（'nix' 无法识别）。

指向虚拟环境的 Python。保存后重新加载 MCP 服务器。

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

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

根据情况调整 command：

同样的模式（python/路径 + ["-m", "nix"]）适用于 Claude Code 和 Copilot。stdout 属于 MCP 协议：日志只写入 ~/.nix/logs/nix.log。

快速开始

在 init 之后（安装程序已经触发）：

# 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

第一次 sync（或任何需要嵌入的操作）会从 Hugging Face 下载 BAAI/bge-m3 模型（约 2.3 GB）。之后的同步只重新处理有变化的内容。

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

索引

这是核心规则：

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

在 Obsidian 中编辑后，运行 nix sync 或让代理执行 sync_index。如果一次写入的向量化失败，文件仍保留在 vault 中（作为事实来源），运行 nix sync 即可修复索引。

CLI

MCP 工具

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

配置

配置文件（按顺序查找第一个）：$NIX_CONFIG → ./nix.toml → ~/.nix/config.toml。NIX_SECAO__CAMPO 环境变量会覆盖配置文件（例如：NIX_VAULT__PATH）。

init 生成的 TOML 中的有用项：

文档

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

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