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는 다음 순서로 동작합니다.

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 서버 설치 및 모델 준비

Terminal

npx @sunub/obsidian-mcp-server setup

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

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

bash

obsidian-mcp-server setup

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

MCP 클라이언트 설정

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

config.json

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

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

환경 변수

환경변수	기본값	용도	필수
`VAULT_DIR_PATH`	없음	Obsidian Vault 절대 경로	예
`LOGGING_LEVEL`	`info`	`debug`, `info`, `warn`, `error`	아니오
`LLM_API_URL`	`http://127.0.0.1:8080`	CLI UI가 사용할 OpenAI 호환 로컬 LLM endpoint	CLI 사용 시
`LLM_CHAT_MODEL`	`llama3`	CLI UI 답변 생성 모델명	CLI 사용 시

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 트리거, 버퍼 오염 같은 문제를 제어합니다.
장시간 세션 안정성 확보: 스트리밍 취소, 히스토리 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는 응답이 끝난 뒤 한 번에 보여주는 구조가 아니라, 생성 중인 상태를 즉시 보여주는 흐름을 중심으로 설계되어 있습니다.

입력 직후 버퍼를 비워 다음 작업을 준비합니다.
첫 토큰 전에는 thinking/processing 상태를 보여줍니다.
완료된 기록은 정적 영역으로 넘기고, 현재 응답만 동적으로 다시 렌더링합니다.

주요 실행 흐름

사용자가 메시지 또는 슬래시 커맨드를 입력합니다.
질문 내용에서 Vault 관련 도구가 트리거되면 관련 문맥 수집을 시도합니다.
LLM 스트리밍 요청을 시작합니다.
필요 시 MCP 도구를 호출합니다.
응답을 실시간으로 출력합니다.
완료된 결과를 히스토리에 반영하고 다음 입력을 기다립니다.

아키텍처 관점에서의 역할

영역	역할	대표 파일
부팅 및 환경 확인	LLM endpoint 확인, 초기 로더/에러 화면 제어	`AppContainer.tsx`, `ui/LLMHealthChecker.tsx`, `ui/LLMStatusLoader.tsx`
MCP 연결 관리	설정 파일 기반 MCP 서버 연결, 도구 목록 수집, 멀티 서버 상태 관리	`hooks/useMcpManager.ts`, `services/McpClientService.ts`, `config/mcpServersConfig.ts`
입력 시스템	Raw key 처리, paste 버퍼링, 멀티라인 편집, 히스토리 탐색	`context/KeypressContext.tsx`, `ui/InputPrompt.tsx`, `key/`
명령 디스패치	슬래시 커맨드를 MCP 도구 호출로 변환	`hooks/useDispatcher.ts`
RAG 컨텍스트 수집	Vault 관련 도구가 트리거된 질문에서만 문맥을 수집해 프롬프트에 주입	`hooks/useRagContext.ts`
LLM 스트리밍 루프	스트리밍 응답, tool call 실행, thinking 파싱	`hooks/useLlmStream/useLlmStream.ts`
렌더링 및 세션 관리	히스토리 출력, pending 응답 표시, transient UI 메시지 관리	`ui/MainContent.tsx`, `hooks/useHistoryManager.ts`
대량 입력 최적화	큰 붙여넣기 입력 오프로딩 및 임시 파일 정리	`services/InputOffloadService.ts`

설계 원칙

이 CLI는 다음 원칙을 중심으로 설계됩니다.

입력과 렌더링의 분리
스트리밍 우선 UX
설정 파일 기반 MCP 연결
도구 호출과 대화 흐름의 통합
토큰/메모리 효율 최적화
중단 가능성과 복구 가능성 보장

제공하는 주요 명령

현재 코드 기준으로 기본 제공되는 대표 슬래시 커맨드는 다음과 같습니다.

/search <keyword>: Vault 하이브리드 검색
/read "filename": 특정 문서 열람
/semantic <query>: 시맨틱 검색
/stats: Vault 상태 확인
/index: 벡터 인덱스 갱신
/context <topic>: 토픽 기반 문맥 수집
/organize <keyword>: 첨부 정리 도구 실행
/genprop <filename>: frontmatter 생성 도구 호출
/tools: 연결된 MCP 도구 목록 확인
/help: 도움말 표시
/clear: 화면/대화 상태 초기화
/quit, /exit: CLI 종료

실행 방법

현재 CLI 진입점은 저장소 개발 환경용 실행 방식입니다. 패키지의 bin 엔트리는 MCP 서버용이며, CLI UI는 루트에서 별도 스크립트로 실행됩니다.

저장소 루트에서 의존성을 설치하고 서버를 먼저 빌드합니다.

Terminal

npm install
npm run build

이 저장소 루트에는 기본 mcp-servers.json이 포함되어 있으며, node ./build/index.js로 서버를 실행합니다.

그 다음 OpenAI 호환 로컬 LLM 서버를 실행합니다. 예를 들어 llama.cpp의 llama-server를 8080 포트에 띄울 수 있습니다.

bash

llama-server -m /path/to/model.gguf --port 8080

CLI는 다음처럼 환경 변수를 주입하여 실행합니다:

bash

VAULT_DIR_PATH="/Users/username/Documents/MyVault" \
LLM_API_URL="http://127.0.0.1:8080" \
LLM_CHAT_MODEL="llama3" \
npm run cli

MCP 설정 파일

CLI는 실행 시 현재 작업 디렉터리에서 다음 파일을 순서대로 찾습니다.

mcp-servers.json
.mcp-servers.json

설정 파일이 없으면 환경 변수 기반 fallback을 시도하지만, 가장 안전한 실행 방식은 저장소 루트에서, build/index.js가 준비된 상태로 실행하는 것입니다.

실행 시 주의할 점

이 CLI 실행 방법은 개발용 CLI UI 진입점 기준입니다. 배포된 npx @sunub/obsidian-mcp-server는 MCP 서버를 띄울 뿐 CLI UI를 실행하지 않습니다.
CLI가 MCP 서버에 연결되려면 현재 디렉터리의 mcp-servers.json 또는 .mcp-servers.json이 유효해야 합니다.
VAULT_DIR_PATH가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.
semantic search와 reranking을 쓰려면 서버 setup으로 로컬 모델을 설치해야 합니다.

주의 사항

VAULT_DIR_PATH가 없거나 잘못되면 Vault 관련 도구가 동작하지 않습니다.
semantic search와 reranking을 쓰려면 setup으로 로컬 모델을 설치해야 합니다.
CLI UI를 쓰려면 별도의 OpenAI 호환 로컬 LLM 서버가 실행 중이어야 합니다.
CLI의 명시적 RAG는 vault 관련 명령, 서버명, 도구명이 입력에서 트리거될 때만 사전 문맥 수집을 시도합니다.
collect_context는 긴 주제 정리와 메모리 패킷 생성에 적합하고, 단건 조회는 search나 read가 더 단순합니다.
쓰기 계열 도구는 Vault 바깥 경로에 쓰지 않도록 차단합니다.

참고 문서

라이선스

Apache-2.0