Storyblocks

Storyblocks MCP

Storyblocks API v2 用の MCP サーバーです。Claude、Cursor、その他の MCP クライアントから、ストック映像、音楽、効果音、写真、ベクター素材を検索し、アイテムのメタデータを取得して、ライセンス付きダウンロードリンクを取得できます。

これは認証情報を持ち込んで使うツールです。Storyblocks から発行された API キーを用意すると、サーバーが Storyblocks の HMAC 方式で各リクエストにローカルで署名します。ホストされるものはなく、秘密鍵がマシンの外に出ることもありません。また、インストールも不要です。依存関係のないプレーンな Node.js サーバーです。

非公式です。 独立したコミュニティ開発プロジェクトであり、Storyblocks とは提携しておらず、Storyblocks による承認やサポートも受けていません。API の利用には、Storyblocks との契約が適用されます。

利用できる機能

• search_videos / search_audio / search_images — API がサポートするすべてのフィルター（コンテンツタイプ、長さ、BPM、向き、色、リリース、エディトリアル、フレームレート、VR、並べ替え、ページネーション、拡張フィールド）
• get_stock_item_details / get_stock_items_details_batch — 完全なメタデータと利用可能なダウンロード形式
• get_download_links — 形式ごとの高品質なライセンス付きダウンロード URL
• find_similar_stock_items — 「これに似たアイテム」
• list_categories / list_collections / get_collection_items — 厳選コンテンツを閲覧
• list_expiring_content — 削除済みでも、期間限定でダウンロードできるアイテム
• whitelist_youtube_channel / file_youtube_audio_dispute / list_valid_claimants — Storyblocks の音声向け YouTube Content ID の申し立てツール
• storyblocks_raw_request — 任意の /api/v2 パスに署名付きでリクエストするためのエスケープハッチ
• リソース storyblocks://docs/api-overview — モデルが読み取れる簡潔な API リファレンス

前提条件：Storyblocks API キー

Storyblocks の公開鍵と秘密鍵が必要です。

• 無料のテストキー（レート制限が低く、内部テストのみ）：https://developer.storyblocks.com/register
• フルアクセスキー：https://www.storyblocks.com/business-solution/api または [email protected]

Storyblocks では、すべての検索とダウンロードに user_id と project_id も必要です。これらはご自身のシステムで使う不透明な識別子（名前やメールアドレスではありません）で、Storyblocks がダウンロードを検索に関連付け、コントリビューターに報酬を支払うために使われます。デフォルト値を一度設定する（以下を参照）か、呼び出しごとに渡すことができます。

Claude Desktop にインストールする（.mcpb）

1. 最新リリースから storyblocks.mcpb をダウンロードします。
2. 設定 → 拡張機能 → 拡張機能をインストールを選択し、ファイルを指定します。
3. 求められたら、公開鍵と秘密鍵を貼り付けます。省略可能なuser id / project id フィールドは空欄のままにします。User and project idsを参照してください。

他の MCP クライアント（Cursor、VS Code、Windsurf など）での使用

内部では標準的な stdio MCP サーバー が動作します。ローカルの MCP サーバーを実行できるクライアントなら、.mcpb は不要で、そのまま使用できます。リポジトリをクローンまたはダウンロードし（npm install もビルド手順も不要です）、クライアントに server/index.js を指定してください。

git clone https://github.com/rocksfrow/storyblocks-mcp.git

Cursor — ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）：

{
  "mcpServers": {
    "storyblocks": {
      "command": "node",
      "args": ["/absolute/path/to/storyblocks-mcp/server/index.js"],
      "env": {
        "STORYBLOCKS_PUBLIC_KEY": "…",
        "STORYBLOCKS_PRIVATE_KEY": "…"
      }
    }
  }
}

VS Code（.vscode/mcp.json）、Windsurf、Claude Desktop（手動設定）では、同じ command + args + env の形式を使用します。異なるのはファイルの場所だけです。

リモート専用クライアント（ChatGPT コネクター、Perplexity など）には HTTPS の MCP URL が必要で、ローカルコマンドを実行できないため、この stdio ビルドを直接追加することはできません。

使用例

• 「海岸線の 4K ドローン映像を、30 秒未満で探して」→ search_videos { keywords: "coastline aerial", quality: "4K", max_duration: 30 }
• 「製品紹介動画向けに、BPM 120 前後のアップテンポなインストゥルメンタルを探して」→ search_audio { keywords: "upbeat corporate", content_type: ["music"], min_bpm: 110, max_bpm: 130, has_vocals: false }
• 「青が多い、夜の東京の横向き写真を探して」→ search_images { keywords: "tokyo night", orientation: "landscape", color: "#1E3A8A" }
• 「アイテム 11851 はどの形式で利用できますか？」→ get_stock_item_details { media_type: "videos", stock_item_id: 11851 }
• 「このクリップのダウンロードリンクを教えて」→ get_download_links { media_type: "videos", stock_item_id: 11851 }
• 「このトラックに似たものをもっと見せて」→ find_similar_stock_items { media_type: "audio", stock_item_id: 148396, limit: 10 }

Storyblocks の検索レスポンスは 10,000 件までです（results_per_page ≤ 250）。list_categories のカテゴリ ID は、対応する content_type とともに categories フィルターに渡せます。

知っておくとよいこと：

• get_download_links はライセンス対象のダウンロードです。 アカウントのダウンロード上限にカウントされるため、閲覧中ではなく、ユーザーがアイテムを選んだ後に呼び出してください。返される URL は CloudFront 署名付きで、発行から約 30 分後に期限切れになります。すぐにダウンロードし、保存しないでください。検索で取得したプレビュー URL とサムネイル URL は公開されており、安全に保持できます。
• 画像の content_type： 通常の写真を含む画像ライブラリの 99% 超が snapshots に分類されているため、photos でフィルタリングするとほとんど結果が返りません。イラストやベクターを探す場合を除き、設定しないでください。
• 検索を絞り込む： keywords に単語（「sunset ocean horizon」など）を追加し、構造化フィルター（min_duration、quality、orientation、categories）を使用してください。required_keywords / filtered_keywords はドキュメントに記載されているとおり（カンマ区切り）に送信されますが、アイテムのキーワード一覧に含まれる語句でも、上流側で結果が 0 件になることが確認されています。その場合、ツールのレスポンスに hint が含まれます。トピックに沿った検索では、sort_by はデフォルトの most_relevant のままにしてください。most_downloaded は一致する候補全体を人気順に並べるため、トピックから外れていても人気のあるクリップが上位に表示されます。
• 利用権限： find_similar_stock_items と list_expiring_content は、すべてのキーで有効になっているわけではありません。403 "API function request is invalid." は、アカウントでエンドポイントが有効化されていないことを意味します（認証情報に問題はありません）。Storyblocks に有効化を依頼してください。
• list_collections は、Storyblocks が数百件のエントリーを含むリスト全体を一度に返すため、クライアント側でページ分割されます（1 ページあたり 50 件、search フィルター）。get_stock_items_details_batch はデフォルトですべての上流ページを取得して統合するため、invalid_stock_ids / stock_ids_not_found は必ず完全な一覧になります（Storyblocks は最終ページでのみこれらを報告します）。

ユーザー ID とプロジェクト ID

Storyblocks では、すべての検索とダウンロードに user_id と project_id が必要です。これらはお客様のシステム内の識別子です。Storyblocks が発行するものではなく、ダッシュボードにも表示されません。Storyblocks がダウンロードを検索に関連付け、サポート案件を再現し、報酬を支払うコントリビューターに対する同一人物による繰り返しのダウンロードを重複排除するために使われます。最後の用途があるため、user_id は時間が経っても変わらない値にする必要があり、名前やメールアドレスを指定してはいけません（値はそのまま送信され、Storyblocks 側でハッシュ化されます）。

個人利用の場合、設定は不要です。サーバーでは次の値が使用されます。

	デフォルト	値の取得元
project_id	storyblocks-mcp	この連携を識別する固定のスラッグ
user_id	mcp- + 16 random hex chars	crypto.randomBytes を使って一度生成し、~/.storyblocks-mcp/user-id に保存されます。そのため、再起動後も変わらず、インストールごとに異なる値になります

このサーバーを、ユーザー ID とプロジェクト ID をすでに持つマルチユーザーアプリケーションに組み込む場合は、STORYBLOCKS_DEFAULT_USER_ID / STORYBLOCKS_DEFAULT_PROJECT_ID を設定するか、各呼び出しで user_id / project_id を渡してください。どちらも ^[A-Za-z0-9_-]+$ に一致する必要があります。一致しない場合、サーバーは起動時（環境変数）またはリクエスト送信前（ツール引数）に値を拒否します。ホスト名、OS のユーザー名、メールアドレスから ID を生成することはありません。STORYBLOCKS_STATE_DIR で状態ファイルの保存先を変更できます。

認証の仕組み

すべてのリクエストには、3 つのクエリパラメーターが含まれます。APIKEY（公開鍵）、EXPIRES（最大 36 時間先までの Unix タイムスタンプ）、および HMAC = hex(HMAC-SHA256(key = privateKey + EXPIRES, data = URL path)) です。署名対象のデータはパスのみで、ホストもクエリー文字列も含みません。ただし、ストックアイテム ID などのパスパラメーターは含まれます。サーバーは server/auth.js でリクエストごとにこの値を計算します。秘密鍵は HMAC の入力にのみ使用され、送信もログへの記録もされません。

Storyblocks はエンドポイントごと、クライアントごとにレート制限を適用します。テスト用キーの制限は、フルアクセスキーよりも低く設定されています。get_download_links はライセンス付きダウンロードのイベントであり、ダウンロード制限の対象になります。

設定（環境変数による上書き）

変数	用途	デフォルト
STORYBLOCKS_PUBLIC_KEY	APIKEY として送信する公開鍵（必須）	—
STORYBLOCKS_PRIVATE_KEY	HMAC の計算に使用する秘密鍵（必須）	—
STORYBLOCKS_DEFAULT_USER_ID	検索／ダウンロード用の代替 user_id（[A-Za-z0-9_-]+）	インストールごとに生成。上記を参照
STORYBLOCKS_DEFAULT_PROJECT_ID	検索／ダウンロード用の代替 project_id（[A-Za-z0-9_-]+）	storyblocks-mcp
STORYBLOCKS_STATE_DIR	生成された user-id ファイルの保存先	~/.storyblocks-mcp
STORYBLOCKS_BASE_URL	API ホスト	https://api.storyblocks.com
STORYBLOCKS_EXPIRES_SECONDS	署名付きリクエストの有効期間（最大 129600）	300
STORYBLOCKS_TIMEOUT_MS	リクエストごとのタイムアウト	30000

空の値、および任意のフィールドが空のままの場合に Claude Desktop が渡す、置換されていない ${user_config.…} プレースホルダーは、未設定として扱われます。

エラー

API エラー（400 不正なパラメーター、403、404 見つからない、429 レート制限）は、HTTP ステータス、Storyblocks からの errors メッセージ、レスポンスに応じたトラブルシューティングのヒントを含むツールエラーとして返されます。"APIKEY header is invalid" を伴う 403 は、キーの誤りまたはシステム時計のずれを意味します。"API function request is invalid." を伴う 403 は、そのエンドポイントがキーに対して有効化されていないことを意味します。

ビルド

npm test               # node:test — HMAC vs. openssl, schema validation, full stdio protocol run against a mock API
npm run mcpb:validate  # validate manifest.json
npm run mcpb:pack      # pack storyblocks.mcpb

vX.Y.Z タグをプッシュすると、CI がチェックを実行し、バンドルをパッケージ化して GitHub Release に添付し、MCP Registry に公開します。

依存関係をゼロにする理由

Node.js の組み込み機能（crypto、fs、readline、グローバルの fetch）のみを使用しているため、node_modules もロックファイルもビルド手順も不要です。サーバー全体は一度に読み通せる数百行で、.mcpb は約 25 KB です。また、API キーと通信の間にサードパーティーのコードが入り込むこともありません。MCP プロトコル自体は十分に小さいため（stdio 上の JSON-RPC：initialize、tools/list、tools/call、resources/*）、SDK に依存するよりも server/index.js で独自に実装するほうがシンプルです。

貢献

CONTRIBUTING.md をご覧ください。

ライセンス

MIT © Kyle Renfrow

---

Storyblocks とは提携しておらず、Storyblocks の推薦を受けているわけでもありません。「Storyblocks」は Footage Firm, Inc. の商標です。Storyblocks API の利用には、Storyblocks との独自の API 契約が適用されます。