SilverBullet

silverbullet-mcp

あらゆる MCP 対応エージェントに、SilverBullet のスペースへの読み書きアクセスを提供する、小さな MCP サーバーです。

依存関係はありません。Python 3 の標準ライブラリのみを使用します。これはトランスレーターであり、MCP ツールの呼び出しを、読み取り、書き込み、削除をすでにサポートしている SilverBullet 内蔵の /.fs HTTP API に転送します。SilverBullet 内に何かをインストールしたり、パッチを適用したりする必要はありません。

一度に読み通せるほど小さく、クライアントが実際に使用する 2 つの MCP トランスポートに対応しています。stdio（Claude Desktop、Cursor などが起動）と、ストリーミング可能な HTTP（リバースプロキシの背後で共有またはリモートアクセス）です。

クイックスタート

サーバーとして実行します。

git clone https://github.com/wicahma/silverbullet-mcp.git
cd silverbullet-mcp
cp .env.example .env      # set MCP_TOKEN, and SB_URL if SilverBullet is elsewhere
set -a; . ./.env; set +a
python3 sb_mcp.py         # streamable HTTP on http://127.0.0.1:9339/mcp

または、クライアントに起動させます。npm で配布されているため、リポジトリをクローンする必要はありません。

SB_URL=http://127.0.0.1:8123 npx -y silverbullet-mcp --stdio

ツール

ツール	引数	機能
list_pages	—	すべての Markdown ページを一覧表示します
read_note	path	ページを読み取ります
write_note	path、content	ページを作成または上書きします
append_note	path、content	ページが存在しない場合は作成して、内容を追記します
delete_note	path	ページを削除します
search_notes	query	大文字と小文字を区別せずに部分文字列を検索し、path:line: text の形式で返します

パスはスペースからの相対パス（Projects/Foo.md）で、.md のみが許可されます。また、.. セグメントは拒否されます。

トランスポート

	stdio	ストリーミング可能な HTTP
起動方法	--stdio、または MCP_STDIO=1	デフォルト
フレーミング	stdin/stdout 上の改行区切り JSON-RPC	POST /mcp
認証	不要。クライアントがすでにプロセスを所有しています	Authorization: Bearer $MCP_TOKEN
適した用途	Claude Desktop、Cursor、サーバーを起動するあらゆるクライアント	リモートまたは共有アクセス、リバースプロキシ、複数のクライアント

どちらのトランスポートも同じコードを使用し、同じ 6 つのツールを公開します。MCP_TOKEN が関係するのは HTTP モードのみです。SB_* 変数は、どちらのモードでも接続先のスペースを指定します。

クライアントの設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "silverbullet": {
      "command": "npx",
      "args": ["-y", "silverbullet-mcp", "--stdio"],
      "env": { "SB_URL": "http://127.0.0.1:8123" }
    }
  }
}

Cursor

同じ内容を、プロジェクトごとに .cursor/mcp.json、またはグローバルに ~/.cursor/mcp.json に記述します。

リモート MCP に対応するクライアント

{
  "mcpServers": {
    "silverbullet": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

リバースプロキシを介さないローカル環境の場合：

{
  "mcpServers": {
    "silverbullet": {
      "type": "http",
      "url": "http://127.0.0.1:9339/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

リモートクライアントへの注意：url は、このブリッジを指すか、このブリッジにプロキシする必要があります。SilverBullet 自体を指してはいけません。SilverBullet には独自の MCP エンドポイントがありません。このプロジェクトが追加するのは、そのエンドポイントです。

設定

設定はすべて環境変数なので、同じコードを誰でも実行できます。

変数	デフォルト	説明
MCP_TOKEN	(空)	HTTP モードでは必須です。 クライアントが送信するベアラートークンです。python3 -c "import secrets; print(secrets.token_urlsafe(32))" で生成できます
SB_URL	http://127.0.0.1:8123	SilverBullet のベース URL です。/.fs にアクセスできる必要があります
SB_AUTH_TOKEN	(空)	任意です。Authorization: Bearer ... として SilverBullet に送信されます
SB_USER_AGENT	silverbullet-mcp/1.0	上流への呼び出しで送信されます。一部の CDN は、Python のデフォルトの urllib シグネチャに対して 403 / エラー 1010 を返します
MCP_HOST	127.0.0.1	バインドアドレス
MCP_PORT	9339	バインドポート
MCP_STDIO	(未設定)	任意の値を設定すると、--stdio と同様に stdio に切り替わります

HTTP エンドポイント

• POST /mcp — JSON-RPC 2.0。ベアラートークンが必要です。通知には 202 を返します。
• GET /health（および GET /mcp/health）— {"status":"ok"} を返します。認証は不要で、内部の詳細情報は公開しません。

ネゴシエートされるプロトコルバージョン：2024-11-05、2025-03-26、2025-06-18。 リクエスト本文の最大サイズは 4 MB です。バッチ配列も受け付けます。

認証

ベアラートークンがアクセス制御の要です。フェイルクローズで動作します。MCP_TOKEN が設定されている場合、一致するトークンがないすべてのリクエストを拒否します。未設定の場合、サーバーは起動します（ローカルでのデバッグ用）が、警告を大きくログに記録します。

トークンなしで、このサーバーをインターネットに公開しないでください。 /mcp にアクセスできる人は誰でも、スペース内のすべてのページを読み取り、上書き、削除できます。

SilverBullet 独自の認証

最近の SilverBullet ビルド（2.10.0 Rust ビルドで確認済み）では、SB_AUTH_TOKEN を設定しただけでは認証は有効になりません。匿名リクエストも引き続き成功します。上流のドキュメントによると、このトークンは代替のベアラーパスにすぎません。サーバーが実際に認証を強制するのは、SB_USER が設定されている場合です。判断に迷う場合は、意図的に誤ったベアラートークンを使って自分のインスタンスを確認してください。それでも 200 が返るなら、認証は無効です。

実際の運用では、認証トークンのゲートは SilverBullet ではなく、このブリッジ（またはリバースプロキシ）に設置してください。

デプロイ

systemd ユーザーユニット

[Unit]
Description=SilverBullet MCP bridge
After=network-online.target

[Service]
EnvironmentFile=%h/silverbullet-mcp.env
WorkingDirectory=%h/silverbullet-mcp
ExecStart=/usr/bin/python3 sb_mcp.py
Restart=on-failure

[Install]
WantedBy=default.target

環境ファイルのモードは 600 にしてください。

リバースプロキシの背後に配置する場合

Cloudflare Tunnel、nginx、Caddy などの背後で問題なく動作します。実際のデプロイで苦労して学んだ注意点が 2 つあります。

• 無料 TLS プランを利用している場合は、既存のホスト名上でパスによるルーティングを設定してください。一部のプロバイダーは、apex ドメインと 1 階層のサブドメインにしか証明書を発行しないため、2 階層のホスト名では TLS ハンドシェイクに失敗することがあります。すでに証明書の対象となっているホストでパスルートを使えば、この問題を完全に回避できます。
• マシンクライアントは SSO を完了できません。ホストが Cloudflare Access などの ID 認識型プロキシの背後にある場合は、MCP パスをバイパスし、ベアラートークンでアクセスを制限してください。通常は、SilverBullet の UI と /.fs API は SSO の背後に置き、/mcp は公開しつつトークンで保護します。

トラブルシューティング

症状	原因
401 unauthorized	クライアントのヘッダーに MCP_TOKEN がない、または値が正しくありません
error code: 1010 を伴う 403	CDN/WAF が上流リクエストの署名を拒否しました。SB_USER_AGENT に識別可能な値を設定し、API パスでマシンクライアントを許可してください
上流から HTML のサインインページが返される、またはブリッジが JSONDecodeError を報告する	SB_URL が SSO の背後にある UI を指しています。/.fs に実際に到達できるアドレス（localhost または内部ホスト名）を指定してください
上流に関する内容を含む HttpError 500 / 502	ブリッジは正常です。SilverBullet が停止しているか、SB_AUTH_TOKEN が正しくありません
設定を編集した後、クライアントにツールが表示されない	クライアントを再起動してください。MCP サーバーは起動時に接続されます
npx がすぐに終了する	python3 が PATH にありません。npm ラッパーは sb_mcp.py を起動するだけです

セキュリティに関する注意事項

• パスは .md のみに制限され、.. による上位ディレクトリへの移動は拒否されます。
• write_note はリビジョン履歴を残さずに上書きします。
• デフォルトではループバックにバインドされ、リバースプロキシのみが受信経路となります。
• search_notes は呼び出しごとにすべてのページを読み込みます。インデックスはありません。
• ブリッジは何も保存しません。起動時に指定された環境以外の状態を保持しないため、いつでも安全に再起動できます。

配布

同じリポジトリから、npm パッケージおよびエージェントプラグインとして公開されています。

npm publish --access public     # package "silverbullet-mcp"

server.json は公式 MCP Registry エントリー（スキーマ 2025-12-11）です。npm パッケージを stdio 経由で実行します。リモートエンドポイントは意図的に宣言していません。デプロイごとに URL が異なるため、掲載したい場合は remotes エントリーを追加してください。

brew install mcp-publisher
mcp-publisher login github
mcp-publisher validate          # validates server.json
mcp-publisher publish

レジストリ名は逆 DNS 形式で、公開に使う GitHub アカウントと一致している必要があります。公開前に、server.json の "name" と package.json の "mcpName" にある OWNER を GitHub のログイン名に置き換えてください。2 つの値は同一でなければなりません。

エージェントプラグインのマニフェストは、.zcode-plugin/plugin.json（ZCode）と、.claude-plugin/plugin.json および .claude-plugin/marketplace.json（Claude Code と skills.sh の構成）にあります。プラグインには MCP サーバーと skills/silverbullet-mcp/ が含まれます。また、クライアントのユーザー設定からベアラートークンを mcp_token として読み込むため、リポジトリに秘密情報が保存されることはありません。

ライセンス

MIT