obsidian-mcp-server

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