Obsidian MCP Server

obsidian-mcp-server는 Obsidian Vault의 Markdown 문서를 AI 에이전트가 조회하고, 관련 근거를 선별하고, 컨텍스트로 압축해 활용할 수 있게 해주는 로컬 우선 MCP 서버입니다.

이 프로젝트에서 RAG는 특정 벡터 DB나 검색 엔진 선택을 뜻하지 않습니다. RAG는 Vault에서 후보 문서를 찾고, Agent 작업에 맞는 근거를 고르고, 컨텍스트 윈도우에 맞게 압축해 제공하는 Agent Context Pipeline입니다.

핵심 방향

• 로컬 우선 동작: 외부 서비스나 별도로 운영해야 하는 검색 엔진 없이 사용자 머신에서 Vault 검색과 컨텍스트 준비를 수행합니다.
• 컨텍스트 선별: 키워드 검색과 시맨틱 검색을 결합해 Agent에게 제공할 근거 후보를 찾습니다.
• 명시적 RAG 통합: 모든 프롬프트에 백그라운드 검색을 붙이지 않고, Vault 관련 명령이나 도구 참조가 있을 때 문맥 수집 경로를 엽니다.
• 토큰 절약: 원문 전체를 밀어넣기보다 excerpt, evidence snippet, memory_packet 형태로 압축합니다.
• 로컬 모델 기반 검색: @huggingface/transformers, LanceDB, local reranker를 사용해 semantic retrieval을 로컬에서 수행합니다.

Elasticsearch 같은 검색 엔진도 retrieval backend로 사용할 수 있는 대안입니다. 다만 이 프로젝트의 기본 목표는 외부 서비스나 별도 검색 엔진에 의존하지 않는 로컬 단독 작업이므로, embedded retrieval stack을 기본값으로 선택합니다.

제공 기능

MCP Tools

• vault
  • search: 키워드와 의미 기반 검색을 결합한 하이브리드 후보 탐색
  • read: 특정 노트 본문과 메타데이터 조회
  • list_all: Vault 문서 목록 조회
  • stats: Vault 및 인덱스 상태 조회
  • collect_context: 주제와 연관된 문서를 선별해 memory_packet 생성
  • load_memory: 저장된 컨텍스트 메모리 스냅샷 로드
• generate_property: 문서 내용을 바탕으로 frontmatter 후보 생성
• write_property: frontmatter 쓰기
• create_document_with_properties: 문서 분석 후 속성 생성/쓰기 2단계 워크플로우
• organize_attachments: 문서 내 첨부파일 정리 및 링크 갱신

Retrieval Pipeline

현재 기본 retrieval backend는 다음 순서로 동작합니다.

1. Keyword Search: 내부 Indexer로 정확한 단어 매칭 후보를 찾습니다.
2. Vector Search: LanceDB와 로컬 embedding model로 의미적으로 유사한 청크를 찾습니다.
3. RRF Fusion: 키워드 결과와 벡터 결과의 순위를 결합합니다.
4. Local Reranking: 상위 후보를 reranker로 다시 평가합니다.
5. Compression: 필요한 excerpt, source ref, memory packet만 Agent context로 제공합니다.

로컬 embedding/reranking 모델이 설치되지 않은 경우 서버는 키워드 검색으로 폴백합니다.

설치

요구사항

• Node.js 22 이상
• 접근 가능한 Obsidian Vault 절대 경로

MCP 서버 설치 및 모델 준비

npx @sunub/obsidian-mcp-server setup

이 명령은 로컬 semantic search와 reranking에 필요한 모델을 캐시에 설치합니다.

이미 패키지를 설치한 환경에서는 다음처럼 실행할 수도 있습니다.

obsidian-mcp-server setup

모델 설치가 없으면 기본 키워드 검색은 동작하지만, semantic search와 reranking 품질은 사용할 수 없습니다.

MCP 클라이언트 설정

Claude Desktop, Cursor, Copilot 등 MCP 클라이언트에는 다음처럼 등록합니다.

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": {
        "VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
      }
    }
  }
}

VAULT_DIR_PATH는 반드시 본인의 Vault 절대 경로로 바꿔야 합니다.

환경 변수

MCP 서버의 Vault 검색/읽기 도구에는 VAULT_DIR_PATH가 핵심 설정입니다. LLM_API_URL과 LLM_CHAT_MODEL은 저장소에 포함된 개발용 CLI UI에서 대화형 스트리밍 답변을 받을 때 필요합니다.

개발용 CLI AI Agent UI

이 저장소에는 터미널 기반 AI Agent UI가 포함되어 있습니다. 이 CLI는 npm 패키지의 공개 bin이 아니라 저장소 개발 환경에서 실행하는 진입점입니다.

이 CLI의 목적은 Obsidian Vault를 단순히 검색하는 수준을 넘어서, MCP 도구 호출, 조건부 RAG 기반 문맥 수집, OpenAI 호환 LLM endpoint 스트리밍 응답을 하나의 대화형 작업 흐름으로 묶는 데 있습니다. 즉, 단순한 "채팅 UI"만 구현하는 곳이 아니라, Vault와 도구, 모델 사이를 연결하는 오케스트레이션 레이어입니다.

왜 이 CLI가 필요한가

프로젝트의 문서와 설계 방향을 기준으로 보면, 이 CLI는 다음 문제를 해결하거나 완화하기 위해 만들어졌습니다.

• 외부 AI 서비스 의존성 감소: 프로젝트가 로컬 Vault와 로컬 도구를 다루는 만큼, 가능한 한 로컬 실행 환경에서 독립적으로 동작하도록 지향합니다.
• 문맥 손실 감소: Vault 관련 도구가 트리거된 질문에서는 관련 문서를 수집하고 요약해 LLM에 함께 전달할 수 있습니다.
• 토큰 낭비 감소: collect_context 기반 압축 요약과 대량 입력 오프로딩을 통해 긴 문서나 대형 paste를 그대로 모델에 밀어넣지 않습니다.
• 터미널 입력 안정성 개선: Raw mode 기반 입력 환경에서 발생하는 paste storm, 다중 Enter 트리거, 버퍼 오염 같은 문제를 제어합니다.
• **장시간 세

... View full README on GitHub