Nix

Obsidianのvaultを開発エージェント（Cursor、Claude Code、Copilot）に公開するMCPサーバー。ノートのハイブリッド検索、読み書き—ローカルで無料のembeddingsとベクトルデータベースを使用。推論はクライアント側で行われ、Nixはツールを提供するだけです。

トランスポート: MCP stdio。サブコマンドなしでnixがサーバーを起動します。

なぜ使うのか

• エディターのエージェントが言葉だけでなくアイデアを見つけます: vault内のセマンティック検索+語彙検索。

• Cursorから離れることなく、Obsidian形式でノートを作成・更新します。

• すべて自分のマシン上で動作します。vaultの一部がembedding APIに送信されることはありません。

• インデックスが更新されるタイミングを自分で制御します: バックグラウンドのwatcherはありません。

Related MCP server: Obsidian MCP Server

要件

• PATHにPython 3.11+

• Obsidianのvault（.mdノート）

• 初回同期時に約2.3GBの空き容量（モデルBAAI/bge-m3のダウンロード）

インストール

2つの方法があります。どちらも.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:/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ではvaultのパスにスラッシュ/を使用します（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"

nixとpython -m nixは、インストーラー実行後（新しいターミナルで）またはvenvをアクティベートした後は同等です。CursorはターミナルのPATHを継承しません — MCPでは常に.venvのPythonを使用してください。

アンインストール

Nixのフォルダーで: uninstall.bat、.\uninstall.ps1またはbash uninstall.shを実行します。sで確認するか、--yesを渡します。これによりPATH、.venv、インデックス（.nix/）、nix.tomlが削除されます。vaultは削除されません。--keep-dataは設定とインデックスを保持します。詳細: INSTALL.md。

MCPクライアントへの登録

クライアントがプロセスを起動します。保存後にMCPサーバーをリロードしてください。

commandはPATH内のnixという名前ではなく、インストールフォルダー内のラッパー（NIX_HOME）を指す必要があります。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にのみ記載されています（リリースのzipにはこのファイルが含まれています）。不足しているものを書き込み、新しいターミナルを開いてください。

最初のsync（または埋め込みを行う任意の操作）は、Hugging FaceからモデルBAAI/bge-m3（約2.3GB）をダウンロードします。以降は、変更されたものだけが再処理されます。

パスにフォルダーがない新しいノートはvault.default_new_note_folder（デフォルトはInbox）に置かれます。

インデックス作成

これが中心的なルールです:

Nixの外部で行われた変更（Obsidian、エディター）は、自動ではインデックスされません。MCPツールによって行われた変更は、同じ操作でインデックスを更新します。

Obsidianで編集した後は、nix syncを実行するか、エージェントにsync_indexを依頼してください。書き込みのベクトル化が失敗した場合、ファイルはvault（真実のソース）に残り、nix syncでインデックスが修正されます。

CLI

MCPツール

12のツール。src/nix/core/tools/registry.pyで定義されています。ノートはリソースnix://note/{+rel_path}としても表示されます。

設定

設定ファイル（最初に見つかったもの）: $NIX_CONFIG（定義されている場合はそれのみ）→ Nixフォルダー内のnix.toml（$NIX_HOMEまたはチェックアウト先）→ CWDおよび親ディレクトリのnix.toml（最後の手段）。相対パスはTOMLのあるディレクトリを基準に解決されます。NIX_SECAO__CAMPO変数はファイルを上書きします（例: NIX_VAULT__PATH）。nix initは同じパスに書き込みます。

initが生成するTOMLの便利なポイント:

バージョンの公開

タグvX.Y.Zがリモートに到達すると、GitHubのリリースが自動的に作成されます。ワークフロー.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ワークフローを確認します。成功すると、リリースNix v1.0.2がzipとチェックサム.sha256とともに表示されます。

既存のタグのアーティファクトを再公開するには、ワークフローを手動で実行します: Actions → Release → Run workflowで、タグを指定します（例: v1.0.2）。

ドキュメント

• PRD.md — 製品、要件、ビジネスルール

• ARCHITECTURE.md — コンポーネント、インデックス作成、検索、MCP stdio