Smart Connections MCP Server

Claude에게 Obsidian 볼트의 진정한 의미 기반 메모리를 제공하세요. 의미를 기준으로 노트를 검색하는 MCP 서버 — Smart Connections Obsidian 플러그인이 이미 생성한 임베딩을 재사용하고, 동일한 임베딩 모델을 로컬에서 실행해 쿼리를 이해합니다. 클라우드 호출이 없으므로 볼트가 컴퓨터 밖으로 나가지 않습니다.

제공 기능

• search_notes — 하나 또는 여러 볼트에 걸친 의미 기반 검색. 전체 노트 및 개별 섹션(블록)을 매칭하며, 유사도 순으로 정렬된 결과를 내용 스니펫과 함께 반환합니다.

• get_similar_notes — 주어진 노트와 유사한 노트(저장된 임베딩).

• get_connection_graph — 유사성 링크를 따라 바깥으로 이동하며 관련 아이디어를 매핑합니다.

• get_note_content — 노트를 읽거나 특정 블록을 추출합니다.

• list_vaults / get_stats — 로드된 항목, 개수, 모델, 로드 오류를 확인합니다.

Related MCP server: ob-smart-connections-mcp

요구 사항

• Node.js 20 이상

• Smart Connections 플러그인이 설치되고 임베딩이 생성된 Obsidian 볼트(v2는 Smart Connections 3.x 데이터로 테스트됨)

• MCP 클라이언트(Claude Desktop, Claude Code, …)

설정 (Claude Desktop)

claude_desktop_config.json에 추가하고 Claude Desktop을 다시 시작하세요:

{
  "mcpServers": {
    "smart-connections": {
      "command": "npx",
      "args": ["-y", "smart-connections-mcp"],
      "env": {
        "SMART_VAULT_PATH": "/path/to/Vault One,/path/to/Vault Two"
      }
    }
  }
}

하나 또는 여러 개의 볼트 — 경로는 쉼표로 구분하세요.

SMART_VAULT_PATHS(복수형)는 SMART_VAULT_PATH의 별칭으로도 허용되며, 둘 다 설정된 경우 SMART_VAULT_PATH보다 우선합니다.

Claude Code

claude mcp add smart-connections -e SMART_VAULT_PATH="/path/to/vault" -- npx -y smart-connections-mcp

작동 방식

Smart Connections는 .smart-env/의 모든 노트와 블록에 대한 임베딩 벡터를 저장합니다. 이 서버는 해당 벡터를 메모리에 로드하고, 검색 시 볼트에서 사용했던 동일한 모델로 쿼리를 임베딩합니다(한 번 다운로드, ~25MB, transformers.js를 통해 로컬에서 실행). 결과는 코사인 유사도로 정렬됩니다. Obsidian에서의 편집 내용은 자동으로 반영됩니다.

임베딩 모델을 로드할 수 없거나(예: 최초 실행 시 네트워크에 연결되지 않은 경우) 볼트에 아직 임베딩이 없는 경우, 검색은 키워드를 문자 그대로 일치시키는 방식으로 대체되며 그 사실을 명시적으로 알려줍니다("mode": "keyword-fallback" 및 원인을 명시하는 warning). 일부 볼트만 대체되는 경우 mode는 "semantic"으로 유지되고, 해당 행은 "match": "keyword"를 가지며, 항상 실제 의미 기반 행 뒤에 정렬됩니다.

v1에서 마이그레이션

• get_embedding_neighbors는 제거되었습니다.

• search_notes는 이제 진정한 의미 기반 검색을 수행하며, 응답에 vault, scope, block, snippet, mode 필드가 포함됩니다.

• 그 외의 모든 것은 하위 호환되며, 단일 볼트용 SMART_VAULT_PATH 설정은 변경 없이 동작합니다.

개발

npm install
npm test              # build + CI-tier tests (no network)
npm run test:live     # + real-model tests (downloads ~25MB once)
npm run smoke -- "/path/to/vault" "your query"

MIT — LICENSE를 참조하세요.