Obsidian Ts MCP

🚀 obsidian-ts-mcp

Obsidianの公式CLIをラップしたモデルコンテキストプロトコル（MCP）サーバーです。VS Code（およびその他のMCPクライアント）内のAIエージェントが、Obsidianボールト内のノートの読み取り、書き込み、検索、管理を行えるようにします。

🚀 クイックスタート

このサーバーを使用することで、AIエージェントがObsidianボールト内のノートを操作できます。以下の手順に従ってセットアップしましょう。

✨ 主な機能

• 37種類のツールを提供し、11のグループに分類されています。
• ノートの作成、読み取り、編集、検索などの基本的な操作が可能です。
• ボールトの情報取得、タグ管理、タスク管理などの高度な機能も備えています。

📦 インストール

git clone https://github.com/dickiedyce/obsidian-ts-mcp.git
cd obsidian-ts-mcp
npm install
npm run build

📚 ドキュメント

前提条件

MCPサーバーを使用する際には、Obsidianデスクトップアプリが実行中である必要があります。また、obsidianバイナリがPATHに含まれている必要があります。

設定

VS Code（ユーザーレベルのMCP）

VS CodeのMCP設定に以下を追加します。

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json（macOSでは~/Library/Application Support/Claude/claude_desktop_config.json、Windowsでは%APPDATA%\Claude\claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

OBSIDIAN_VAULTには、対象とするボールトの名前を設定します。この名前は、Obsidianのボールト切り替え画面に表示される名前と完全に一致する必要があります。

環境変数

利用可能なツール

サーバーは37種類のツールを提供し、11のグループに分類されています。

コア - ノート管理

探索とコンテキスト

プロパティとメタデータ

タスク

日次ノート（拡張）

テンプレート

リンク

プロパティ（拡張）

タグ（拡張）

ファイル管理

ベース

プロジェクト管理

プロジェクト構造

src/
  cli.ts          -- 低レベルのObsidian CLIラッパー（実行、引数の構築、エラー処理）。
  fs-ops.ts       -- 正確なパス制御のための直接のファイルシステム操作（ディレクトリ作成、読み取り、書き込み）。
  tools.ts        -- MCPツールの定義（名前、説明、JSONスキーマ）。
  handlers.ts     -- ツール呼び出し（37種類のツール）をCLIコマンドまたはファイルシステム操作にルーティングします。
  server.ts       -- MCPサーバーのエントリポイント（stdioトランスポート、エラー処理）。
  validation.ts   -- ツールスキーマに対する入力検証。
tests/
  cli.test.ts           -- 引数の構築とエラータイプの単体テスト。
  fs-ops.test.ts        -- ファイルシステム操作の単体テスト。
  runObsidian.test.ts   -- CLI実行、タイムアウト、ボールトターゲティングのテスト。
  handlers.test.ts      -- すべての37種類のツールハンドラーのテスト（CLIとfs-opsはモックされます）。
  tools.test.ts         -- すべてのツール定義のスキーマ検証。
  validation.test.ts    -- 入力検証テスト（型、列挙型、必須フィールド）。
  server.test.ts        -- サーバーファクトリ、エラーフォーマット、バージョンチェック。

開発

npm run dev           # ウォッチモードでTypeScriptをコンパイルします。
npm test              # テストスイートを一度実行します。
npm run test:watch    # ウォッチモードでテストを実行します。
npm run test:coverage # カバレッジレポート付きでテストを実行します。
npm run build         # 一度だけコンパイルします。
npm run lint          # ESLintを実行します。
npm run format:check  # Prettierのフォーマットをチェックします。
npm start             # stdioでMCPサーバーを起動します。

動作原理

1. MCPクライアント（VS Code、Claude Desktopなど）がstdioを介してサーバーを起動します。
2. クライアントがtools/listを呼び出し、src/tools.tsから37種類のツール定義を受け取ります。
3. クライアントがツールを呼び出すと、src/server.tsが呼び出しをsrc/handlers.tsのhandleTool()にルーティングします。
4. handleTool()は入力をツールスキーマに対して検証し、src/cli.tsのbuildArgs()とrunObsidian()を使用して対応するobsidian CLIコマンドを実行するか、正確なパス制御が必要な場合はsrc/fs-ops.tsの直接のファイルシステム操作を使用します（例：サブディレクトリにノートを作成する場合、プロジェクト管理）。
5. CLIの出力は、テキストコンテンツブロックとしてクライアントに返されます。

テスト

テストはVitestを使用し、CLIレイヤーをモックするため、実際のObsidianバイナリを呼び出すことはありません。以下のコマンドを実行します。

npm test

セキュリティに関する考慮事項

• 完全なボールトアクセス：サーバーは対象のボールト内のすべてのノートに読み書きアクセス権を持っています。OBSIDIAN_VAULTを、AIエージェントに公開しても問題ないボールトに制限してください。
• 認証なし：stdioトランスポートには組み込みの認証がありません。アクセス制御は、サーバープロセスを起動できるユーザーに完全に依存します。
• 入力検証：すべてのツール入力は、実行前に宣言されたスキーマに対して検証されます。サーバーはexecFile（execではなく）を使用してシェルインジェクションを回避しますが、ファイル/パスの値は直接Obsidian CLIに渡されることに注意してください。
• 環境継承：子プロセスは親の環境変数を継承します。サーバープロセスに表示される環境変数にシークレットを保存しないでください。

トラブルシューティング

📄 ライセンス

MIT