Nix

MCP 서버로, Obsidian 볼트를 개발 에이전트(Cursor, Claude Code, Copilot)에 노출합니다. 하이브리드 검색, 노트 읽기/쓰기 — 로컬 및 무료 임베딩과 벡터 데이터베이스를 사용합니다. 추론은 클라이언트에 남고, Nix는 도구만 제공합니다.

전송: MCP stdio. 하위 명령 없이 nix가 서버를 시작합니다.

사용 이유

• 에디터 에이전트가 단어만이 아니라 아이디어를 찾습니다: 볼트에서 의미론적 + 어휘적 검색.

• Cursor를 떠나지 않고 Obsidian 형식으로 노트를 만들고 업데이트합니다.

• 모든 것이 사용자 컴퓨터에서 실행됩니다. 볼트의 어떤 부분도 임베딩 API로 전송되지 않습니다.

• 인덱스가 변경되는 시점을 직접 제어합니다: 백그라운드 watcher가 없습니다.

Related MCP server: Obsidian MCP Server

요구 사항

• PATH에 Python 3.11+

• Obsidian 볼트(.md 노트)

• 첫 번째 동기화 시 약 2.3GB 여유 공간(BAAI/bge-m3 모델 다운로드)

설치

두 가지 방법이 있습니다. 둘 다 .venv를 만들고, 패키지를 설치한 다음 nix init을 실행합니다(볼트 경로를 묻거나 --vault를 허용합니다).

프로젝트에 설치 (사용자)

1. 최신 릴리스(nix-x.y.z.zip)를 다운로드합니다.

2. workspace 루트에 압축을 풀고 폴더 이름을 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"

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이 제거됩니다. 볼트는 삭제되지 않습니다. --keep-data는 구성과 인덱스를 보존합니다. 자세한 내용: INSTALL.md.

MCP 클라이언트 등록

클라이언트가 프로세스를 시작합니다. 저장한 후 MCP 서버를 다시 로드하세요.

command는 PATH의 nix 이름이 아니라 설치 폴더 안의 wrapper(NIX_HOME)를 가리켜야 합니다. Dock이나 메뉴에서 연 에디터는 터미널의 PATH를 상속하지 않습니다(spawn nix ENOENT). 경로는 nix doctor의 comando nix: 줄에 표시됩니다.

Cursor — workspace의 .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를 요청하세요. 쓰기 작업의 벡터화가 실패하면 파일은 볼트(진실의 원천)에 남아 있고, 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의 유용한 항목:

버전 게시

GitHub 릴리스는 vX.Y.Z 태그가 원격 저장소에 도착하면 자동으로 생성됩니다. .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