Obsidian Local Rest Api MCP

🚀 Obsidian Local REST API MCP Server

このサーバーは、ローカルのREST APIを通じてObsidianボールトとやり取りするための、AIネイティブなMCP（Model Context Protocol）サーバーです。タスク指向のインテリジェントなツールを提供し、Obsidianボールトの操作を効率的に行うことができます。

🚀 クイックスタート

このサーバーを使用することで、Obsidianボールトの操作をAIによってより効果的に行うことができます。以下に、サーバーのセットアップと使用方法を説明します。

✨ 主な機能

🧠 AIネイティブな設計哲学

このMCPサーバーは、AIネイティブな原則に基づいて再設計されています。低レベルのCRUD操作ではなく、LLMがより効果的に推論できる高レベルのタスク指向のツールを提供します。

変更前と変更後の比較

🛠 利用可能なツール

ディレクトリとファイル操作

• list_directory 目的: ページネーションでディレクトリの内容をリストし、コンテキストオーバーフローを防ぐ

  {
    "path": "Projects/",
    "recursive": false,
    "limit": 20,
    "offset": 0
  }
  

  AIの利点: LLMがコンテキストを圧倒することなく、ボールト構造を段階的に探索できる

• read_file 目的: ボールト内の任意のファイルの内容を読み取る

  {"path": "notes/meeting-notes.md"}
  

• write_file 目的: 複数のモードでファイルを書き込み、作成/更新操作を統合する

  {
    "path": "notes/summary.md",
    "content": "# Meeting Summary\n...",
    "mode": "append"  // "overwrite", "append", "prepend"
  }
  

  AIの利点: 単一のツールですべての書き込みシナリオを処理し、曖昧さを排除する

• delete_item 目的: 任意のファイルまたはディレクトリを削除する

  {"path": "old-notes/"}
  

AIネイティブなノート操作

• create_or_update_note 目的: インテリジェントなアップサート - 存在しない場合は作成、存在する場合は更新する

  {
    "path": "daily/2024-12-26",
    "content": "## Tasks\n- Review AI-native MCP design",
    "frontmatter": {"tags": ["daily", "tasks"]}
  }
  

  AIの利点: 「このノートは存在するか？」という判断の木を排除する

• get_daily_note 目的: 一般的な命名パターンでスマートに日次ノートを取得する

  {"date": "today"}  // or "yesterday", "2024-12-26"
  

  AIの利点: ファイルシステムの詳細と命名規則を抽象化する

• get_recent_notes 目的: 最近変更されたノートを取得する

  {"limit": 5}
  

  AIの利点: 「最近何に取り組んだか？」という自然なクエリに対応する

高度な検索と発見

• search_vault 目的: 高度なフィルタリングを備えたマルチスコープ検索

  {
    "query": "machine learning",
    "scope": ["content", "filename", "tags"],
    "path_filter": "research/"
  }
  

  AIの利点: 正確なターゲット検索でノイズを減らす

• find_related_notes 目的: ノート間の概念的な関係を発見する

  {
    "path": "ai-research.md",
    "on": ["tags", "links"]
  }
  

  AIの利点: 関係ベースのワークフローと偶然の発見を可能にする

レガシーツール（下位互換性）

サーバーは、get_note、list_notes、get_metadata_keys などの既存のツールとの下位互換性を維持しています。

📦 インストール

前提条件

• Node.js 18+ またはBunランタイム
• Obsidian Local REST API をローカルで実行（デフォルト: http://obsidian-local-rest-api.test）

npxを使用する場合（推奨）

npx obsidian-local-rest-api-mcp

ソースからインストールする場合

# リポジトリをクローンする
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# Bunで依存関係をインストールする
bun install

# プロジェクトをビルドする
bun run build

設定

API接続のための環境変数を設定します。

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # デフォルトURL（または非Valetセットアップの場合はhttp://localhost:8000）
export OBSIDIAN_API_KEY="your-api-key"          # オプションのベアラートークン

💻 使用例

サーバーの起動

# 自動リロード付きの開発モード
bun run dev

# 本番モード
bun run start

# または直接実行
node build/index.js

MCPクライアントの設定

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["obsidian-local-rest-api-mcp"],
      "env": {
        "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
        "OBSIDIAN_API_KEY": "your-api-key-if-needed"
      }
    }
  }
}

MCP拡張機能を持つVS Code

含まれている .vscode/mcp.json 設定ファイルを使用します。

Cherry Studioの設定

Cherry Studioでは、以下の設定を使用します。

• 名前: obsidian-vault（任意の名前でも可）
• タイプ: Standard Input/Output (stdio)
• コマンド: npx
• 引数: obsidian-local-rest-api-mcp
• 環境変数:
  • OBSIDIAN_API_URL: あなたのAPI URL（例: Laravel Valetの場合は http://obsidian-local-rest-api.test）
  • OBSIDIAN_API_KEY: 認証が必要な場合はオプションのAPIキー

開発

# 開発用のウォッチモード
bun run dev

# TypeScriptをビルドする
bun run build

# 型チェック
bun run tsc --noEmit

🔧 技術詳細

アーキテクチャ

• ObsidianApiClient - REST APIエンドポイントのHTTPクライアントラッパー
• ObsidianMcpServer - ツールハンドラーを持つMCPサーバーの実装
• Configuration - 検証付きの環境ベースの設定

エラーハンドリング

サーバーには包括的なエラーハンドリングが含まれています。

• API接続エラー
• 無効なツールパラメーター
• ネットワークタイムアウト
• 認証エラー

エラーは、説明的なメッセージを含むMCPツール呼び出し応答として返されます。

デバッグ

環境変数を設定してデバッグログを有効にします。

export DEBUG=1
export NODE_ENV=development

サーバーログはstderrに書き込まれ、stdoutでのMCPプロトコル通信に干渉しないようになっています。

トラブルシューティング

MCPサーバーが起動しない場合

MCPクライアントが「起動失敗」または同様のエラーを表示する場合:

1. サーバーを直接テストする:

   npx obsidian-local-rest-api-mcp --version
   

   バージョン番号が出力されるはずです。

2. MCPプロトコルをテストする:

   # テストスクリプトを実行する
   node -e "
   const { spawn } = require('child_process');
   const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
   child.stdout.on('data', d => console.log('OUT:', d.toString()));
   child.stderr.on('data', d => console.log('ERR:', d.toString()));
   setTimeout(() => {
     child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
     setTimeout(() => child.kill(), 2000);
   }, 500);
   "
   

   初期化応答が表示されるはずです。

3. 環境変数を確認する:

   • OBSIDIAN_API_URL が実行中のObsidian Local REST APIを指していることを確認する
   • APIを直接テストする: curl http://obsidian-local-rest-api.test/api/files（またはあなたが設定したAPI URL）

4. Obsidian Local REST APIを確認する:

   • Obsidian Local REST API をインストールして実行する
   • 設定したポートでアクセス可能であることを確認する
   • 認証が必要かどうかを確認する

一般的な問題

• "Command not found": Node.js/npmがインストールされており、npxが利用可能であることを確認する
• "Connection refused": Obsidian Local REST APIが実行されていないか、URLが間違っている可能性がある
• Laravel Valetの.testドメイン: Laravel Valetを使用する場合は、プロジェクトディレクトリ名が.testドメインと一致することを確認する（例: /obsidian-local-rest-api/ のプロジェクトの場合は obsidian-local-rest-api.test）
• "Unauthorized": APIキーが必要かどうかを確認し、正しく設定されていることを確認する
• "Timeout": クライアント設定でタイムアウトを増やすか、ネットワーク接続を確認する

貢献方法

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 適切なTypeScript型を使用して変更を加える
4. あなたのObsidianボールトでテストする
5. プルリクエストを送信する

📄 ライセンス

MIT