Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
The MCP server “ai.smithery/sunub-obsidian-mcp-server” helps an AI agent query a local Obsidian Vault. It finds Markdown notes by title or keyword, selects relevant evidence, and compresses related content into context suitable for the agent’s context window.
🛠️ Key Features
Local-first Obsidian Vault search on the user’s machine
Retrieves notes by title or keyword
Selects relevant supporting content for agent use
Compresses related content to fit an agent context window
RAG is defined as an Agent Context Pipeline (candidate retrieval → evidence selection → context compression)
🚀 Use Cases
Quickly locate relevant notes inside an Obsidian vault
Produce summarized, context-compressed background from related vault content
⚡ Developer Benefits
Explicit pipeline behavior for “agent context” (not tied to a specific vector DB or search engine)
Combines keyword search and semantic search to gather evidence candidates
⚠️ Limitations
The provided source excerpt does not specify tool names, counts, or supported MCP interfaces.
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는 다음 순서로 동작합니다.
Keyword Search: 내부 Indexer로 정확한 단어 매칭 후보를 찾습니다.
Vector Search: LanceDB와 로컬 embedding model로 의미적으로 유사한 청크를 찾습니다.
RRF Fusion: 키워드 결과와 벡터 결과의 순위를 결합합니다.
Local Reranking: 상위 후보를 reranker로 다시 평가합니다.
Compression: 필요한 excerpt, source ref, memory packet만 Agent context로 제공합니다.
로컬 embedding/reranking 모델이 설치되지 않은 경우 서버는 키워드 검색으로 폴백합니다.
설치
요구사항
Node.js 22 이상
접근 가능한 Obsidian Vault 절대 경로
MCP 서버 설치 및 모델 준비
bash
npx @sunub/obsidian-mcp-server setup
이 명령은 로컬 semantic search와 reranking에 필요한 모델을 캐시에 설치합니다.
이미 패키지를 설치한 환경에서는 다음처럼 실행할 수도 있습니다.
bash
obsidian-mcp-server setup
모델 설치가 없으면 기본 키워드 검색은 동작하지만, semantic search와 reranking 품질은 사용할 수 없습니다.
MCP 클라이언트 설정
Claude Desktop, Cursor, Copilot 등 MCP 클라이언트에는 다음처럼 등록합니다.
MCP 서버의 Vault 검색/읽기 도구에는 VAULT_DIR_PATH가 핵심 설정입니다. LLM_API_URL과 LLM_CHAT_MODEL은 저장소에 포함된 개발용 CLI UI에서 대화형 스트리밍 답변을 받을 때 필요합니다.
개발용 CLI AI Agent UI
banner
이 저장소에는 터미널 기반 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 트리거, 버퍼 오염 같은 문제를 제어합니다.
장시간 세션 안정성 확보: 스트리밍 취소, 히스토리 pruning, scrollback 위임 같은 구조를 통해 메모리 사용량과 렌더링 부담을 줄입니다.
이 CLI가 하는 일
1. 대화형 AI 인터페이스
사용자는 터미널에서 자연어로 질문을 입력하고, CLI는 LLM 서버와 통신해 답변을 스트리밍합니다.
응답을 실시간으로 출력합니다.
모델의 thinking 영역이 있으면 중간 추론 상태도 별도로 렌더링합니다.
완료된 대화는 히스토리에 반영하고, 진행 중 응답은 별도 pending 상태로 관리합니다.
2. MCP 도구 실행 인터페이스
CLI는 MCP 서버에 연결된 도구를 터미널에서 직접 사용할 수 있게 합니다.
/search, /read, /stats, /context, /tools 같은 슬래시 커맨드를 제공합니다.
사용자의 명시적 명령뿐 아니라, LLM이 tool call을 생성했을 때도 이를 실행할 수 있는 루프를 제공합니다.
여러 MCP 서버에 연결하고, 각 서버의 도구 목록과 연결 상태를 함께 관리합니다.
3. 조건부 RAG 기반 문맥 주입
이 CLI는 모든 일반 질문에 대해 자동으로 RAG를 수행하지는 않습니다. 현재 구현 기준으로는 입력 텍스트에서 vault 도구나 관련 서버/도구 이름이 트리거된 경우에만 Vault 문맥 수집을 시도하고, 이를 <context> 블록으로 정리해 프롬프트에 주입합니다.
collect_context 액션을 활용해 관련 문서를 배치 단위로 수집합니다.
memory_packet과 고연관 문서 excerpt를 조합해 LLM 입력을 구성합니다.
따라서 이 CLI는 항상 RAG가 붙는 채팅창이라기보다, 필요 시 Vault-aware 동작을 수행하는 agent UI에 가깝습니다.
4. 대용량 입력 최적화
긴 코드, 로그, 문서가 붙여넣기되면 이를 그대로 모델에 보내는 대신 안전하게 축약/오프로딩합니다.
큰 paste는 임시 파일로 분리해 저장합니다.
LLM에는 전체 본문 대신 파일 위치와 미리보기, 처리 지시문을 전달합니다.
이 방식은 토큰 사용량을 줄이고, 필요할 때만 도구를 통해 원문을 읽게 만듭니다.
5. 스트리밍 중심 사용자 경험
CLI UI는 응답이 끝난 뒤 한 번에 보여주는 구조가 아니라, 생성 중인 상태를 즉시 보여주는 흐름을 중심으로 설계되어 있습니다.
