Hint-Services-obsidian-github-mcp

Obsidian GitHub MCP

Obsidian vault を含む GitHub リポジトリに AI アシスタントを接続する Model Context Protocol（MCP）サーバーです。このサーバーにより、GitHub に保存されているナレッジベースとシームレスに連携でき、AI アシスタントが Obsidian のノートやドキュメントを読み取り、検索、分析できるようになります。

このツールを選ぶ理由

多くの Obsidian ユーザーは、バックアップ、バージョン管理、共同作業のために vault を GitHub に保存しています。この MCP サーバーは、GitHub 上の Obsidian vault と AI アシスタントの間をつなぎ、次のことを可能にします。

• ナレッジベースへのアクセス：Obsidian vault から特定のノートやドキュメントを取得します
• インテリジェント検索：ナレッジベース全体から関連するコンテンツを見つけます
• 変遷の追跡：アイデアやノートが時間とともにどのように発展してきたかを確認できます
• タスク連携：イシューやプロジェクト管理のワークフローと連携します

機能

• GitHub リポジトリへのアクセス：Obsidian vault を含む任意の GitHub リポジトリに接続します
• 型安全な実装：包括的な型定義を備えた TypeScript で記述されています
• 入力検証：Zod スキーマを使用して、すべての API 入力を堅牢に検証します
• エラー処理：わかりやすいメッセージを伴う、適切なエラー処理を行います
• MCP 連携：Claude、Cursor、Windsurf、Cline など、さまざまな MCP ホストと完全に互換性があります

利用可能なツール

ナレッジベースへのアクセス

• getFileContents：Obsidian vault から特定のノート、ドキュメント、ファイルの内容を取得します
• searchFiles：複数のモードを備えた拡張検索：
  • filename：ファイル名を完全一致で検索します（「OKR 2025」のような検索に最適です）
  • path：ファイルパス内の任意の場所を検索します
  • content：ファイルの内容を検索します
  • all：ファイル名、パス、内容を対象に包括的に検索します

プロジェクト管理との連携

• searchIssues：ナレッジベースのプロジェクトに関連するイシューやディスカッションを検索します
• getCommitHistory：詳細なコミット履歴と差分を使って、ナレッジベースが時間とともにどのように変化したかを追跡します

ユースケース

ナレッジワーカー向け

• リサーチアシスタント：AI がリサーチノートや参考資料にアクセスできます
• 執筆支援：ナレッジベースから関連する背景情報を取得できます
• アイデアの発展：ノートを通じてコンセプトがどのように発展したかを追跡できます

開発者向け

• ドキュメントへのアクセス：プロジェクトのドキュメントや技術ノートを取得できます
• 学習記録：学習ノートやコード例にアクセスできます
• プロジェクト計画：GitHub のイシューと連携し、包括的なプロジェクト管理を実現できます

学生・研究者向け

• 学習教材：講義ノートや学習ガイドにアクセスできます
• 研究論文：リサーチノートや引用情報を取得できます
• 共同作業：GitHub に保存された共有ナレッジベースを使って作業できます

インストール

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

Obsidian GitHub MCP をインストールする最も簡単な方法は、Smithery を使用することです。

# For Claude Desktop
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client claude

# For Cursor
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cursor

# For Windsurf
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client windsurf

# For Cline
npx -y @smithery/cli install @Hint-Services/obsidian-github-mcp --client cline

手動インストール

npm install obsidian-github-mcp

設定

次の設定を使用して、MCP 設定ファイルにサーバーを追加します。

{
  "mcpServers": {
    "obsidianGithub": {
      "command": "npx",
      "args": ["-y", "obsidian-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your-github-token",
        "GITHUB_OWNER": "your-github-username",
        "GITHUB_REPO": "your-obsidian-vault-repo"
      }
    }
  }
}

必須の環境変数

• GITHUB_TOKEN：GitHub の個人用アクセストークン（こちらから作成）
• GITHUB_OWNER：GitHub リポジトリの所有者または組織
• GITHUB_REPO：Obsidian vault を含むリポジトリの名前

GitHub トークンの権限

GitHub トークンには、次の権限が必要です。

• repo（プライベートリポジトリの場合）または public_repo（パブリックリポジトリの場合）
• read:org（組織のリポジトリにアクセスする場合）

ワークフローの例

デイリーノートへのアクセス

{
  "tool": "getFileContents",
  "arguments": {
    "filePath": "Daily Notes/2024-01-15.md"
  }
}

ファイル名で検索（「OKR 2025」の例に最適です！）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

パスでファイルを検索

{
  "tool": "searchFiles",
  "arguments": {
    "query": "Daily Notes",
    "searchIn": "path"
  }
}

トピックに関する調査結果の検索（コンテンツ検索）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "machine learning algorithms",
    "searchIn": "content",
    "perPage": 10
  }
}

包括的な検索（ファイル名、パス、コンテンツ）

{
  "tool": "searchFiles",
  "arguments": {
    "query": "project planning",
    "searchIn": "all"
  }
}

GitHub の高度な検索構文

{
  "tool": "searchFiles",
  "arguments": {
    "query": "path:*.md extension:md",
    "searchIn": "content"
  }
}

ナレッジの変遷を追跡する

{
  "tool": "getCommitHistory",
  "arguments": {
    "days": 30,
    "includeDiffs": true,
    "maxCommits": 10
  }
}

検索のヒントとトラブルシューティング

ファイル名でファイルが見つからない場合

問題：「OKR 2025」を検索しても、「OKR 2025.md」という名前のファイルが見つかりません。

解決策：searchIn: "filename" パラメーターを使用します。

{
  "tool": "searchFiles",
  "arguments": {
    "query": "OKR 2025",
    "searchIn": "filename"
  }
}

高度な検索テクニック

1. 完全一致フレーズ：複数単語の検索では引用符を使用します。

   {
     "query": "\"project planning 2025\"",
     "searchIn": "content"
   }
   

2. ファイル拡張子：特定の種類のファイルを検索します。

   {
     "query": "path:*.md",
     "searchIn": "content"
   }
   

3. ディレクトリを指定：フォルダー内を検索します。

   {
     "query": "path:\"Daily Notes/\"",
     "searchIn": "content"
   }
   

プロジェクト構成

obsidian-github-mcp/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   └── github/           # GitHub API integration
│       ├── client.ts     # GitHub client implementation
│       └── types.ts      # TypeScript type definitions
├── docs/                 # Documentation
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

開発者向け

このプロジェクトへの貢献や、このサーバーを使った独自のツールの開発に関心がある場合は、開発ガイドをご覧ください。

開発コマンド

• pnpm install - 依存関係をインストールします
• pnpm run build - プロジェクトをビルドします
• pnpm run dev - インスペクターを使って開発モードで実行します
• pnpm run inspector - テスト用に MCP インスペクターを起動します

mcp-private-github-search からの移行

以前の mcp-private-github-search パッケージから移行する場合：

1. 設定でパッケージ名を更新します。

   {
     "mcpServers": {
       "obsidianGithub": {
         "command": "npx",
         "args": ["-y", "obsidian-github-mcp"]
       }
     }
   }
   

2. 機能は変わりません。既存のツールはすべて同じように動作します。

3. Obsidian に特化した新しいユースケースとワークフローをご検討ください。

詳細情報

MCP エコシステムの詳細については、以下をご覧ください。

• Model Context Protocol のドキュメント：MCP のアーキテクチャと設計原則を詳しく解説しています
• Smithery - MCP サーバーレジストリ：MCP サーバーの公開に関するガイドライン
• MCP TypeScript SDK のドキュメント：TypeScript SDK の包括的なドキュメント
• Obsidian：このツールの着想のもととなったナレッジ管理アプリ

Hint Services について

「未来はすでにここにある。ただ、均等に行き渡っていないだけだ」

— William Gibson、作家

Hint Services は、ユーザーインターフェースが人工知能技術を活用する方法を開発し、拡大することを使命とするブティックコンサルティング会社です。AI とユーザーエクスペリエンスが交差する領域で、野心的な構想を設計しています。Ben Hofferber が創業し、率いています。

開発者になることなく AI ツールを活用したいデザインチーム向けに、専門的な AI ワークショップを提供しています。トレーニングとワークショップの詳細はこちら。