Obsidian GitHub MCP

Obsidian GitHub MCP

選択した AI エージェントが、GitHub に保存された Obsidian の保管庫への変更を、制限付きかつ監査可能な形で提案できるようにする、ホワイトラベルの Model Context Protocol サーバーです。

各エージェントには、有効期限付きの MCP ベアラートークンが個別に発行されます。GitHub の認証情報はサーバー側に保持されます。読み取りと書き込みのパス、拒否、保護対象の領域、提案ブランチ、トークンの失効は、運用者が管理する YAML ファイルで制御します。

これは独立したオープンソースプロジェクトです。Obsidian または GitHub とは提携しておらず、承認も受けていません。

なぜ使うのですか？

エージェントに汎用的な GitHub トークンを渡すと、制約を設けるのが難しく、誤用も簡単です。このサーバーは、より限定された境界を設けます。

AI agent + individual MCP token
        |
        v
identity + fixed broker
        |
        v
agent write scope AND broker publication scope
        |
        v
deny, path, frontmatter, mutability, size, and secret checks
        |
        v
server-side GitHub App token
        |
        v
proposal branch for human review

このサービスには、ファイルの削除、ブランチのマージ、main または master へのプッシュ、リポジトリ設定の変更、ワークフローの編集、認証情報の公開を行うツールはありません。

機能

• ステートレスな MCP Streamable HTTP トランスポート
• SHA-256 バインディングとして保存される、一意で有効期限付きのベアラートークン
• エージェントごとの読み取り、書き込み、拒否のパス glob
• Git ブローカーごとの個別の許可リストと固定の提案ブランチ
• 共有領域または機密領域に対する、設定可能なフロントマター要件
• living、review-first、append-only、immutable によるノートの処理
• パストラバーサルの防止と、ファイル拡張子／サイズの許可リスト
• 認証情報に類似する内容の検出
• リポジトリを制限した GitHub App トークンと、ローカルテスト用の PAT フォールバック
• 内容を記録しない JSONL 監査レコード
• ホスト／オリジンの検証、セキュリティヘッダー、レート制限、HTTP タイムアウト
• Docker、CI、テスト、デプロイのドキュメント

MCP ツール

ツール	目的
vault_whoami	認証された ID、ブローカー、ブランチ、ポリシーのスコープを表示します。
vault_list_allowed_paths	有効な読み取り／書き込み／拒否の境界を説明します。
vault_explain_access	1 つのパスをドライランします。読み取り、一覧表示、書き込みが許可されるか、およびその判断に適用されるポリシールールを報告します。GitHub への呼び出しは行いません。
vault_list_files	拒否された子項目を除外しながら、許可されたディレクトリを一覧表示します。
vault_read_file	許可された UTF-8 の保管庫ファイルを読み取ります。
vault_create_file	ID に固定された提案ブランチにファイルを作成します。
vault_update_file	可変性を尊重しながら、許可されたファイルを更新します。
vault_append_file	既存のすべてのバイト列を保持しながら追記します。

要件

• Node.js 22+
• GitHub リポジトリ内の Obsidian 保管庫
• ブローカーごとの専用の非デフォルト提案ブランチ
• 保管庫のリポジトリのみにインストールした、Contents: read and write 権限を持つ GitHub App、またはローカルテスト用のきめ細かい PAT

クイックスタート

ソースからインストールします（現在サポートされている方法）。

git clone https://github.com/YOUR_ACCOUNT/obsidian-github-mcp.git
cd obsidian-github-mcp
npm ci
cp .env.example .env
cp config/policy.example.yaml config/policy.yaml
cp config/tokens.example.yaml config/tokens.yaml
npm run token:new
npm run check
# Configure .env with your GitHub repository and token/app credentials before starting:
npm start

.env を設定し（リポジトリと、GITHUB_TOKEN または GitHub App の認証情報を指定します）、サンプルポリシーを置き換えて、生成されたトークンの SHA-256 のみを config/tokens.yaml に記入します。生のベアラートークンは、MCP クライアント 1 つだけに渡してください。

実行中のサービスを設定する前に、チェックアウトを検証するには次のコマンドを実行します。

npm ci
npm run check
npm run test:e2e

これらのチェックでは、合成ノート、モックの GitHub 応答、ループバックトランスポートを使用します。 GitHub や MCP の認証情報は不要です。リグレッションテストでは、Unicode／パスのエンコーディング、CRLF のフロントマター、不正なメタデータ、UTF-8 のサイズ制限、追記専用時のバイト列保持を確認します。CI では、Linux と Windows 上で Node.js 22 および 24 を使い、同じチェックを実行します。上記の 8 つのツールが現在のサーバー機能です。テストによって実際の保管庫に提案が公開されることはありません。

v0.1.0 が npm に公開されると、グローバルインストールも利用できるようになります。

# Available once v0.1.0 is published (not yet on the npm registry).
npm install -g @sarutobi-sasuke/obsidian-github-mcp

デフォルトのエンドポイントは次のとおりです。

GET  http://127.0.0.1:3210/healthz
POST http://127.0.0.1:3210/mcp

MCP クライアントは次の内容を送信する必要があります。

Authorization: Bearer vault_<generated-token>

権限モデル

有効な書き込みスコープは、エージェントへの許可と、そのブローカーとの共通部分です。

policy_version: 1
authority: operator-only

agents:
  - id: example-writer
    name: Example Writer
    role: bounded knowledge worker
    disclosure_ceiling: internal
    entry_reads: [README.md]
    read: [Knowledge/**, Workspace/**]
    write: [Workspace/Shared/**, Workspace/Example Writer/**]
    deny: [Private/**, People/**, .obsidian/**]

git_brokers:
  - broker: example-writer
    branch: agent/example-writer
    allow: [Workspace/Shared/**, Workspace/Example Writer/**]

never_versioned: [Private/**, People/**, .obsidian/**, secrets/**]

surface_rules:
  - path: Workspace/Shared/**
    required_frontmatter:
      disclosure: public-safe

認証バインディングは、1 つのトークンハッシュをその ID とブローカーに対応付けます。このバインディングによって、ポリシーで許可されていないパスが許可されることはありません。

プロビジョニングと失効については、権限に関するドキュメントを参照してください。

GitHub 認証

本番環境へのデプロイでは、Vault リポジトリのみにインストールした GitHub App を使用してください。次のように設定します。

GITHUB_APP_ID=123456
GITHUB_APP_INSTALLATION_ID=12345678
GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/vault-mcp.pem

サーバーは、設定済みリポジトリと contents: write に再度制限した、有効期間の短いインストールトークンを作成します。ローカル開発用の代替手段として、リポジトリにスコープを限定した GITHUB_TOKEN もサポートされています。

デプロイ

同梱のコンテナーは、非 root ユーザーとして読み取り専用のルートファイルシステムで実行されます。サービスをリモートからアクセス可能にする前に、TLS、プライベートオーバーレイネットワーク、または認証済みゲートウェイをサービスの前段に配置してください。

デプロイガイドを参照してください。

検証

npm run check
npm audit --audit-level=high

テストでは、ポリシーの解析、書き込みスコープの積集合、拒否ルールの優先、パストラバーサルの試行、フロントマターのルール、変更可能性、シークレットの検出、トークンのバインド、およびブランチを固定した GitHub への書き込みを検証します。

npm run test:e2e を実行すると、クリーンな tarball のインストールと、テスト専用の GitHub 代替環境を使った実際の MCP HTTP クライアントによる検証を行います。提案の書き込み、拒否対象のパス／コンテンツ、変更不可および追記専用のノート、古い書き込みによる競合、無効なポリシーの再読み込み、実行中のトークン失効、コンテンツを含まない監査記録をテストします。CI では Windows／Linux 上で Node 22/24 を使用してこの検証を実行し、リリースワークフローでも必須となっています。

ポリシーファイルとトークンファイルでは、未知のキーは拒否されます。サポートされるのは policy_version: 1 と authority: operator-only のみです。スペルミスのあるフィールドを修正するか、サポート対象外のメタデータを削除してからアップグレードしてください。制限が黙って無視されることはなくなりました。リリースの検証結果と残るゲート。

MCP Registry への npm 登録案内では、stdio サーバーではなく、セルフホスト型の Streamable HTTP プロセスについて説明しています。互換性のあるクライアントは、宣言された環境変数を設定してプロセスを起動し、http://127.0.0.1:{VAULT_MCP_PORT}/mcp（デフォルトのポートは 3210）に接続します。既存のポリシーファイルとトークンファイルのパスに加え、リポジトリの所有者名／名前を指定してください。GitHub にアクセスするには、GITHUB_TOKEN を使用するか、文書に記載された GitHub App の 3 つすべての変数を指定します。マニフェストではこの代替グループを表現できませんが、実行時の設定で検証されます。このプロセスは、認証情報を作成したり、ホストされたエンドポイントをプロビジョニングしたり、既存のベアラートークン検証を回避したりすることはありません。名前空間では、GitHub の所有者名の大文字・小文字をそのまま保持します。prepublishOnly にはレジストリ／パッケージのゲートが含まれますが、ログインや公開は実行されません。

セキュリティ

デプロイ前にセキュリティポリシーをお読みください。脆弱性が疑われる場合は、悪用の詳細を含む公開 issue を作成せず、非公開で報告してください。

ライセンス

Apache-2.0。Apache-2.0 ライセンスを参照してください。