Obsidian MCP ツールサーバー

このプロジェクトは、Obsidian Vault と対話するためのツールを公開する Model Context Protocol (MCP) サーバーを提供します。

特徴

MCP クライアント (AI アシスタントなど) に次の機能を許可します。

メモを読んだり書いたりする
ノートのメタデータ（フロントマター）を管理する
メモとフォルダを一覧表示する
コンテンツまたはメタデータでノートを検索
日々のメモを管理する
発信リンク、バックリンク、タグを取得する

インストール

リポジトリのクローンを作成します(まだ作成していない場合)。
# git clone <repository-url> # cd OMCP
プロジェクトディレクトリに移動します:
cd /path/to/your/OMCP
Python 仮想環境を作成します(依存関係の競合を避けるために推奨)。
python -m venv .venv
仮想環境をアクティブ化します:
- Windows PowerShell の場合:
  .venv\Scripts\Activate.ps1
- Linux/macOSの場合:GXP5 (ターミナルプロンプトの先頭に(.venv)と表示されるはずです)
パッケージとその依存関係をインストールします。
pip install .

構成

このサーバーは環境変数を使用して構成され、プロジェクトルートの.envファイルを使用して簡単に管理できます。

サンプルファイルをコピーします。
# From the project root directory (OMCP/) cp .env.example .env
(Windows では、 copy .env.example .envを使用できます)
**.envファイルを編集する:**新しく作成した.envファイルをテキストエディターで開きます。
OMCP_VAULT_PATHを設定してください。これは必須の変数です。Obsidian Vault への絶対パスで更新してください。Windows でも、パスにはスラッシュ ( / ) を使用してください。
OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"
**オプション設定の確認：**必要に応じて、日々のメモ、サーバーポート、バックアップディレクトリなどのOMCP_変数を調整してください。説明については、ファイル内のコメントをご覧ください。

(または、 .envファイルを使用する代わりに、これらを実際のシステム環境変数として設定することもできます。両方が設定されている場合、サーバーは.envファイルよりもシステム環境変数を優先します。)

手動で実行（テスト/デバッグ用）

Claude Desktop などのクライアントアプリケーションは、以下に説明する構成を使用してサーバーを自動的に起動しますが、直接テストまたはデバッグするためにターミナルからサーバーを手動で実行することもできます。

**構成が完了していることを確認する:**構成セクションで説明されているように、 .envファイルを作成して構成したことを確認します。
仮想環境をアクティブ化します:
# If not already active .venv\Scripts\Activate.ps1
(Linux/macOSではsource .venv/bin/activate使用してください)
サーバースクリプトを実行します。
(.venv) ...> python obsidian_mcp_server/main.py

サーバーが起動し、リッスンしているアドレス（例： http://127.0.0.1:8001 8001）を表示します。テストが終了したら、通常はCtrl+Cを押してサーバーを停止します。

注意：このサーバーをClaude Desktopや同様のランチャーと併用する場合は、このように手動で実行しないでください。代わりにクライアントアプリケーションを設定してください（次のセクションを参照）。クライアントアプリケーションがサーバープロセスの起動と停止を処理します。

クライアント構成（例：Claude Desktop）

多くのMCPクライアント（Claude Desktopなど）は、サーバープロセスを直接起動できます。このようなクライアントを設定するには、通常、JSON設定ファイル（例：macOS/Linuxではclaude_desktop_config.json 、WindowsではAppData配下）を編集する必要があります。

⚠️重要な JSON フォーマット規則:

JSONファイルはコメントをサポートしていません（ //または/* */コメントを削除してください）
すべての文字列は二重引用符（ " ）で適切に囲む必要があります。
Windows のパスではエスケープされたバックスラッシュ ( \\ ) を使用する必要があります。
JSONバリデータ（ jsonlint.comなど）を使用して構文をチェックします。

クライアントの JSON 構成のmcpServersキーの下に追加するエントリの例を次に示します。

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"],
      "env": {
        "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault",
        "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily"
      }
    }
  }
}

要点:

パスをシステムに関連する絶対パスに置き換えます
commandおよびargsフィールドの Windows パスの場合:
- パス区切りには二重のバックスラッシュ（ \\ ）を使用します
- Python実行ファイルには.exe拡張子を付けます
envブロック内の Windows パスの場合:
- 互換性を高めるためにスラッシュ（ / ）を使用してください
- .exe拡張子を含めないでください
commandパスは、作成した.venv内のpython.exe実行可能ファイルを指す必要があります。
argsパスは、 obsidian_mcp_serverサブフォルダ内のmain.pyファイルを指す必要があります。
envブロックを使用することは、サーバーがVaultパスを確実に見つけられるようにするための最も信頼できる方法です。
JSON設定を変更した後は**、クライアントアプリケーションを必ず再起動して**ください。

避けるべきよくある落とし穴:

Windowsのパスでは単一のバックスラッシュを使用しないでください
JSONにコメントを含めない
Windowsのパスではバックスラッシュをエスケープすることを忘れないでください
同じパス内でスラッシュとバックスラッシュを混在させないでください
すべての文字列を適切に引用符で囲むことを忘れないでください

利用可能なMCPツール

list_folders
list_notes
get_note_content
get_note_metadata
get_outgoing_links
get_backlinks
get_all_tags
search_notes_content
search_notes_metadata
search_folders
create_note
edit_note
append_to_note
update_note_metadata
delete_note
get_daily_note_path
create_daily_note
append_to_daily_note

ロードマップ

このプロジェクトは現在開発中です。計画されている機能は以下のとおりです。

v1.x (近い将来)

テンプレートベースのノート作成:
- テンプレートディレクトリ ( OMCP_TEMPLATE_DIR ) を構成します。
- create_note_from_templateツールを実装します (テンプレート名、ターゲットパス、オプションのメタデータを使用)。
- テンプレート作成のテストを追加します。
フォルダーの作成:
- create_folderユーティリティ関数を実装します。
- create_folder MCP ツールを実装します。
- フォルダー作成のテストを追加します。

v1.y (中期/将来の機能強化)

テンプレート内の変数の置換 (例: {{DATE}} )。
list_templatesツール。
高度なノート更新ツール (例: append_to_note_by_metadata )。
包括的な Vault 階層を表示するためのlist_vault_structureツール。
包括的なテストの見直しと拡張。

v2.x+ (潜在的なアイデア / 長期的)

整理ツール:
- move_item(source, destination) (初期バージョンではリンクが更新されない可能性があります)。
- rename_item(path, new_name) (初期バージョンではリンクが更新されない可能性があります)。
コンテンツ操作ツール:
- replace_text_in_note(path, old, new, count) 。
- prepend_to_note(path, content) 。
- append_to_section(path, heading, content) (信頼性の高い見出し解析が必要です)。
クエリツール:
- get_local_graph(path) (発信リンクとバックリンクを結合します)。
- search_notes_by_metadata_field(key, value) 。
プラグイン統合ツール:
- データビュー統合:
  - execute_dataview_query(query_type, query) - データビュークエリを実行し、構造化された結果を取得します。
  - search_by_dataview_field(field, value) - データビューフィールドでノートを検索
- タスク管理:
  - query_tasks(status, due_date, tags) - 保管庫全体のタスクを検索およびフィルタリングします
- カンバン統合:
  - get_kanban_data(board_path) - 構造化されたカンバンボードデータを取得する
- カレンダー統合:
  - get_calendar_events(start_date, end_date) - カレンダーのイベントとタスクを照会する

よくある質問（FAQ）

構成の問題

Q: サーバーがVaultを見つけられません。何が問題なのでしょうか？ A: これは通常、パスの設定が間違っていることが原因です。以下をご確認ください。

.envファイルのOMCP_VAULT_PATHは、Windowsでもスラッシュ（ / ）を使用します。
パスは絶対パスです（ルートから始まります）
パスの末尾にスラッシュが付いていない
ボールトディレクトリが存在し、アクセス可能です

Q: 権限エラーが発生するのはなぜですか? A: これは通常、次のような場合に発生します。

ボールトパスが制限されたディレクトリを指しています
Pythonプロセスには読み取り/書き込み権限がありません
保管庫は、現在同期中のクラウド同期フォルダ（OneDriveなど）にあります

試す：

保管庫をローカルディレクトリに移動する
昇格された権限でサーバーを実行する
ウイルス対策ソフトがアクセスをブロックしていないか確認する

クライアント接続の問題

Q: AIクライアントがサーバーに接続できません。何を確認すればよいですか？ A: 以下のよくある問題を確認してください。

サーバーは実際に実行されています（ターミナル出力を確認してください）
クライアント設定のポートがサーバーのポートと一致している
クライアント設定のPythonパスが正しい仮想環境を指している
すべての環境変数がクライアント設定で適切に設定されている

Q: 「接続が拒否されました」というエラーが表示されるのはなぜですか? A: これは通常、次のことを意味します。

サーバーが稼働していません
ポートはすでに使用されています
ファイアウォールが接続をブロックしています

試す：

サーバーが実行中かどうかを確認します: netstat -ano | findstr :8001 (Windows)
.envでOMCP_SERVER_PORTを設定して別のポートを試してください
テストのためにファイアウォールを一時的に無効にする

Q: 「[error] [obsidian_vault] 予期しないトークン 'S'、"Starting O"... は有効なJSONではありません」というエラーが表示されます。何が問題なのでしょうか？ A: このエラーは、クライアントのJSON設定ファイルが不正な場合に発生します。一般的な原因:

JSONにカンマが不足しているか、余分なカンマがあります
Windows パス内のエスケープされていないバックスラッシュ
JSON 内のコメント (JSON はコメントをサポートしていません)

クライアント構成ファイル (例: claude_desktop_config.json ) を確認します。

JSONバリデータ（ jsonlint.comなど）を使用して構文をチェックする
Windows のパスの場合は、バックスラッシュをエスケープします: "C:\\path\\to\\file"
コメント（// または /* */）を削除します。
すべての文字列が適切に引用符で囲まれていることを確認する
すべての括弧と中括弧が適切に閉じられているか確認してください

正しい Windows パス形式の例:

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"]
    }
  }
}

Q: タイムアウトエラーが発生し、「サーバーが切断されました」というメッセージが表示されます。何が起こっているのでしょうか？ A: このエラーパターン（初期化は成功し、60秒後にタイムアウトする）は通常、以下のことを意味します。

サーバーはすでに別のプロセスで実行されています
ポートはすでに別のアプリケーションによって使用されています
サーバープロセスが予期せず終了しました

以下の手順を順番に試してください。

実行中のサーバープロセスを確認します。
# On Windows netstat -ano | findstr :8001 # Look for the PID and then: taskkill /F /PID <PID>
# On Linux/macOS lsof -i :8001 # Look for the PID and then: kill -9 <PID>
ポートを使用している他のアプリケーションを確認します。
- ポート8001を使用する可能性のある他のアプリケーションをすべて閉じます
- これには、他のMCPサーバー、開発サーバー、または任意のWebアプリケーションが含まれます。
- よくわからない場合は、 .envのポートを変更してみてください。
  OMCP_SERVER_PORT=8002
サーバープロセスを確認します:
- タスクマネージャー（Windows）またはアクティビティモニター（macOS）を開きます
- MCPサーバーに関連するPythonプロセスを探します
- 疑わしいプロセスをすべて終了する
システムリソースを確認します。
- 十分なメモリとCPUが利用可能であることを確認してください
- ウイルス対策ソフトウェアやセキュリティソフトウェアがプロセスをブロックしていないか確認してください
- Python環境に適切な権限があることを確認する
すべてをリセットします:
- クライアントアプリケーションを停止する
- 残っているサーバープロセスをすべて終了する
- .envファイルを削除し、 .env.exampleから新しいファイルを作成します。
- コンピュータを再起動します（他の手順が機能しない場合）
- クライアントアプリケーションを新しく開始する

これらすべての手順を試しても問題が解決しない場合は、次の情報を共有してください。

完全なエラーログ
netstat -ano | findstr :8001 (Windows) またはlsof -i :8001 (Linux/macOS) の出力
システムのイベントログからのエラーメッセージ

Q: 「サーバートランスポートが予期せず終了しました…プロセスが早期に終了しました」というメッセージが表示され、サーバーがすぐに切断されます。何が問題なのでしょうか？ A: このエラーは、Pythonサーバープロセスがクライアントによって起動された直後にクラッシュしたことを意味します。タイムアウトではなく、サーバースクリプト自体の実行または実行継続に失敗したことを意味します。

一般的な原因:

クライアント JSON 内のパスが正しくありません:
- command``.venv内の正しいpython.exeを指していません。
- args正しいobsidian_mcp_server/main.pyスクリプトを指していません。
- Windows でパス区切り文字が正しくないか、バックスラッシュエスケープ ( \\ ) が欠落しています。
不足している依存関係:
- requirements.txtの必須パッケージが.venvにインストールされていません。
- クライアントは仮想環境を適切にアクティブ化せずに Python を起動しています。
**構文エラー:**最近のコード変更により、Python 構文エラーが発生しました。
重大な構成/権限エラー:
- 起動時に.envファイルの読み取りエラーが発生しました。
- OMCP_VAULT_PATH無効またはアクセスできません。
- Python プロセスには、ファイルを実行またはアクセスする権限がありません。
**早期の未処理例外:**サーバーがリッスンを開始する前の初期セットアップ中にエラーが発生しました。

トラブルシューティングの手順:

**クライアントのJSONパスの確認：**クライアントのJSON設定で、 commandとargsの絶対パスを再確認してください。Windowsパスにはエスケープされたバックスラッシュ（ \\ ）を使用してください。
手動でテストする（重要なステップ）:
- ターミナルで仮想環境をアクティブ化します。
  # On Windows .\.venv\Scripts\activate
  # On Linux/macOS source .venv/bin/activate
- サーバーを直接実行します。
  python obsidian_mcp_server/main.py
- ターミナルに直接表示されるエラーメッセージを注意深く確認してください。これによりクライアントを経由せずに、多くの場合、根本的な原因（ ImportError 、 SyntaxError 、 FileNotFoundErrorなど）が明らかになります。
依存関係を確認する: venv を有効にした状態で、 pip checkとpip install -r requirements.txt実行します。
.env.env Vault Path を検証します。.envが存在し、読み取り可能であり、 OMCP_VAULT_PATH正しいことを確認します (スラッシュ/使用)。
**最近のコード変更を確認する:**最近編集した Python ファイルの構文エラーや問題を確認します。

ノート操作

Q: 特定のフォルダでメモを作成/編集できないのはなぜですか? A: 考えられる原因は次のとおりです。

パスのセキュリティ制限（ボールト外への書き込みを試行）
フォルダの権限
他のプロセスからのファイルロック

試す：

保管庫内での相対パスの使用
フォルダの権限を確認しています
ファイルを開いている可能性のある他のプログラムを閉じる

Q: ノートの更新が保存されないのはなぜですか? A: よくある原因:

ノートのパスが間違っています
コンテンツの形式が無効です
バックアップの作成に失敗しました

チェック：

ノートパスが存在し、アクセス可能です
コンテンツは有効なマークダウンです
バックアップディレクトリには書き込み権限があります

日々のメモ

Q: 毎日のメモが正しい場所に作成されないのはなぜですか? A: 確認:

OMCP_DAILY_NOTE_LOCATIONが.envで正しく設定されている
パスにはスラッシュが使用されています
対象フォルダが存在します
日付の形式は保管庫の設定と一致します

一般的なトラブルシューティング

Q: サーバーが正しく動作しているかどうかを確認するにはどうすればよいですか? A: テストクライアントを実行します。

python test_client.py

これにより、一連の操作が実行され、問題があれば報告されます。

Q: エラーログはどこにありますか? A: 確認してください:

サーバーが稼働している端末
失敗した操作のバックアップディレクトリ
権限の問題に関するシステムイベントログ

Q: すべてをリセットして最初からやり直すにはどうすればよいですか? A: 次の手順を試してください。

サーバーを停止する
.envファイルを削除する
.env.exampleから新しい.envを作成する
サーバーを再起動します

貢献を歓迎します!

Obsidian MCP Tool Server

Integrations