sunub-obsidian-mcp-server

Obsidian MCP Server

obsidian-mcp-serverは、Obsidian Vault の Markdown ドキュメントを AI エージェントが検索し、関連する根拠を選別し、コンテキストとして圧縮して活用できるようにする、ローカル優先の MCP サーバーです。

このプロジェクトでの RAG は、特定のベクトル DB や検索エンジンの選択を意味するものではありません。RAG は、Vault から候補ドキュメントを探し、エージェントの作業に合った根拠を選び、コンテキストウィンドウに合わせて圧縮して提供する エージェントコンテキストパイプラインです。

主な方針

• ローカル優先の動作：外部サービスや別途運用が必要な検索エンジンを使わず、ユーザーのマシン上で Vault の検索とコンテキストの準備を行います。
• コンテキストの選別：キーワード検索とセマンティック検索を組み合わせ、エージェントに提供する根拠の候補を探します。
• 明示的な RAG 統合：すべてのプロンプトにバックグラウンド検索を付加するのではなく、Vault 関連のコマンドやツール参照があるときに、コンテキスト収集の経路を開きます。
• トークンの節約：原文全体をそのまま渡すのではなく、excerpt、evidence snippet、memory_packetの形式で圧縮します。
• ローカルモデルを使った検索：@huggingface/transformers、LanceDB、ローカル reranker を使って、セマンティック検索をローカルで実行します。

Elasticsearch のような検索エンジンも、retrieval backend として利用できる選択肢です。ただし、このプロジェクトの基本目標は、外部サービスや別の検索エンジンに依存せずローカル単体で動作させることなので、組み込みの 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. キーワード検索：内部のIndexerで、正確に単語が一致する候補を探します。
2. ベクトル検索：LanceDB とローカル embedding model を使って、意味的に類似したチャンクを探します。
3. RRF フュージョン：キーワード検索とベクトル検索の結果の順位を統合します。
4. ローカル再ランキング：上位候補を reranker で再評価します。
5. 圧縮：必要な excerpt、source ref、memory packet のみをエージェントのコンテキストとして提供します。

ローカルの embedding／reranking モデルがインストールされていない場合、サーバーはキーワード検索にフォールバックします。

インストール

要件

• Node.js 22 以上
• アクセス可能な Obsidian Vault の絶対パス

MCP サーバーのインストールとモデルの準備

npx @sunub/obsidian-mcp-server setup

このコマンドは、ローカルのセマンティック検索と再ランキングに必要なモデルをキャッシュにインストールします。

すでにパッケージがインストールされている環境では、次のように実行することもできます。

obsidian-mcp-server setup

モデルをインストールしなくてもデフォルトのキーワード検索は動作しますが、セマンティック検索と再ランキングの品質は利用できません。

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 の絶対パスに置き換えてください。

環境変数

環境変数	デフォルト値	用途	必須
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 エージェント UI

このリポジトリには、ターミナルベースの AI エージェント UI が含まれています。この CLI は npm パッケージの公開binではなく、リポジトリの開発環境で実行するエントリーポイントです。

この CLI の目的は、Obsidian Vault を単に検索するだけでなく、MCP ツールの呼び出し、条件付き RAG によるコンテキスト収集、OpenAI 互換 LLM endpoint からのストリーミング応答を、1つの対話型ワークフローにまとめることです。つまり、単なる「チャット UI」を実装する場所ではなく、Vault、ツール、モデルをつなぐオーケストレーションレイヤーです。

この CLI が必要な理由

プロジェクトのドキュメントと設計方針に基づくと、この CLI は次の問題を解決、または緩和するために作られています。

• 外部 AI サービスへの依存を低減：このプロジェクトではローカルの Vault とツールを扱うため、可能な限りローカルの実行環境で独立して動作することを目指します。
• コンテキストの損失を低減：Vault 関連のツールがトリガーされる質問では、関連ドキュメントを収集して要約し、LLM に併せて渡すことができます。
• トークンの無駄を低減：collect_contextによる圧縮要約と大量入力のオフロードを通じて、長いドキュメントや大きな貼り付け内容を、そのままモデルに渡さないようにします。
• ターミナル入力の安定性を向上：Raw mode に基づく入力環境で発生する paste storm、複数の Enter によるトリガー、バッファーの破損などの問題を制御します。
• 長時間セッションの安定性を確保：ストリーミングのキャンセル、履歴のプルーニング、スクロールバックへの委任などの仕組みにより、メモリ使用量とレンダリングの負荷を軽減します。

この 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 상태를 보여줍니다.
• 완료된 기록은 정적 영역으로 넘기고, 현재 응답만 동적으로 다시 렌더링합니다.

주요 실행 흐름

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

아키텍처 관점에서의 역할

영역	역할	대표 파일
부팅 및 환경 확인	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는 루트에서 별도 스크립트로 실행됩니다.

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

npm install
npm run build

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

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

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

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

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는 실행 시 현재 작업 디렉터리에서 다음 파일을 순서대로 찾습니다.

1. mcp-servers.json
2. .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 바깥 경로에 쓰지 않도록 차단합니다.

참고 문서

• Tool Reference
• Tool Usage Guide
• collect_context Guide

라이선스

Apache-2.0