toshitana/obsidian-mcp-server
3.1
If you are the rightful owner of obsidian-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Obsidian MCP Server is a RAG-compatible system that manages and searches Obsidian Vaults using a Model Context Protocol server.
Obsidian MCP Server
MCP (Model Context Protocol) サーバーによるObsidian Vaultの管理と検索を可能にするRAG対応システム
🚀 主な改善点
1. Chroma DBによる永続化
- メモリベースのベクターストアからChroma DBに移行
- Embeddingの永続化により、再起動時の再計算を回避
- 分散環境での利用が可能
2. 差分更新システム
- ファイルごとのコンテンツハッシュによる変更検出
- 更新日時とハッシュの二重チェックで確実な差分検出
- 変更されたファイルのみEmbedding再作成
3. キャッシュシステム
.embedding-cache.json
による状態管理- ファイルごとのメタデータ(更新日時、ハッシュ、Document ID)を保存
- 起動時に前回の状態から差分のみ更新
4. 重複防止とID管理
- 決定的なDocument ID生成により重複を防止
- ファイルパスとチャンクインデックスから一意のIDを生成
- 同じコンテンツは常に同じIDを持つ
5. 初期化の最適化
- キャッシュ存在時は変更ファイルのみ読み込み
- 初回起動とそれ以降で異なる処理パス
- メモリ使用量を削減
📊 パフォーマンス改善
Before(問題点)
- 起動時に全ファイルのEmbedding再作成
- ファイル変更時に全Vector Store再構築
- OpenAI APIの大量呼び出しによるコスト増大
- 同じチャンクが重複して追加される問題
After(改善後)
- 起動時は変更ファイルのみEmbedding作成
- ファイル変更時は該当ファイルのみ更新
- APIコールを最小限に削減(最大90%削減)
- 決定的なID生成により重複を完全に防止
- 2回目以降の起動時間を大幅に短縮(数秒以内)
🛠 セットアップ
1. Chroma DBのセットアップ
# Dockerでの起動(推奨)
docker run -d -p 8000:8000 chromadb/chroma
# または、ローカルインストール
pip install chromadb
chroma run --host localhost --port 8000
2. 環境変数の設定
# 必須
OPENAI_API_KEY=your-openai-api-key
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# オプション(デフォルト: http://localhost:8000)
CHROMA_URL=http://localhost:8000
3. インストール
npm install
npm run build
4. MCPクライアントの設定
Claude Desktop の場合 (~/Library/Application Support/Claude/claude_desktop_config.json
):
{
"mcpServers": {
"obsidian-vault": {
"command": "node",
"args": ["/path/to/obsidian-mcp-server/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
"OPENAI_API_KEY": "sk-your-openai-api-key",
"CHROMA_URL": "http://localhost:8000"
}
}
}
}
📝 機能
1. search_vault - セマンティック検索
{
"query": "プロジェクト管理",
"max_results": 5
}
- RAG対応でコンテキストを考慮した検索
- 類似度スコア付きの結果返却
2. add_note - ノート追加
{
"title": "2024年プロジェクト計画",
"content": "## 概要\n\n今日の会話で決定した内容...",
"tags": ["project", "2024", "planning"]
}
- 自動的にfrontmatterとタグを付与
- 重複ファイル名の自動処理
3. list_recent_notes - 最近のノート一覧
{
"limit": 10
}
- 最近更新されたノートの一覧表示
4. reset_database - データベースリセット
{
"confirm": true
}
- ベクターデータベースの完全リセット
- キャッシュのクリアと全ファイルの再インデックス
- 不整合が発生した場合の復旧用
🔧 技術スタック
- TypeScript: 型安全な実装
- Chroma DB: ベクターデータベース(永続化対応)
- LangChain: Embedding・ベクター検索フレームワーク
- OpenAI Embeddings: text-embedding-3-small
- MCP SDK: Model Context Protocol実装
- Chokidar: ファイル監視
📂 ディレクトリ構造
obsidian-mcp-server/
├── src/
│ └── index.ts # メインサーバー実装
├── dist/ # ビルド出力
├── package.json
├── tsconfig.json
└── README.md
🔍 技術仕様
ベクターストア
- 埋め込みモデル: OpenAI
text-embedding-3-small
- チャンクサイズ: 1000文字
- オーバーラップ: 200文字
- 永続化: Chroma DB
キャッシュシステム
- キャッシュファイル:
.embedding-cache.json
- 保存場所: Vaultディレクトリ内
- 内容: ファイルハッシュ、更新日時、Document ID
- 更新タイミング: ファイル変更検出時に自動更新
Document ID管理
- ID生成方式: MD5ハッシュ(ファイルパス + チャンクインデックス)
- 重複防止: 決定的なID生成により同一チャンクの重複を防止
- 一貫性: 同じファイルの同じチャンクは常に同じIDを持つ
ファイル監視
.obsidian
などの隠しディレクトリは除外- マークダウンファイル(
.md
)のみを対象 - リアルタイムでファイルの変更を検知
🚨 注意事項
- Chroma DBが起動していることを確認してください
- 初回起動時は全ファイルのEmbedding作成のため時間がかかります
.embedding-cache.json
はVaultディレクトリに自動生成されます- 大規模なVault(1000ファイル以上)の場合、初回起動に数分かかる場合があります
- 2回目以降の起動は差分のみ処理するため高速です(通常数秒以内)
- データベースの不整合が発生した場合は
reset_database
ツールを使用してください
🐛 トラブルシューティング
Chroma DBに接続できない
# Dockerが起動しているか確認
docker ps | grep chroma
# 起動していない場合
docker run -d -p 8000:8000 chromadb/chroma
ベクターストアが初期化されない
- OpenAI APIキーが正しく設定されているか確認
- Vault内にマークダウンファイルが存在するか確認
キャッシュが効かない
.embedding-cache.json
の権限を確認- ディスク容量が十分にあるか確認
重複エントリが発生する場合
// reset_databaseツールを使用してリセット
{
"tool": "reset_database",
"confirm": true
}
- データベースとキャッシュを完全にリセットして再構築
- 全ファイルの再インデックスが実行される
パフォーマンスの問題
- 初回起動が遅い: 全ファイルのEmbedding作成のため正常な動作です
- 2回目以降も遅い: キャッシュが正しく動作していない可能性
.embedding-cache.json
が存在するか確認- ファイルの読み書き権限を確認
📄 ライセンス
MIT