Storyblocks

Storyblocks MCP

一个适用于 Storyblocks API v2 的 MCP 服务，可通过 Claude、Cursor 或任何 MCP 客户端搜索库存视频、音乐、音效、照片和矢量图，获取素材元数据，并获取已授权的下载链接。

这是一个自带凭据的工具：你提供 Storyblocks 发给你的 API 密钥，服务会在本地使用 Storyblocks 的 HMAC 方案为每个请求签名。无需托管任何内容，你的私钥也永远不会离开你的设备，而且无需安装任何内容——该服务是纯 Node.js 程序，零依赖。

非官方。 这是一个由社区独立构建的项目，与 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 字段留空——参见用户 ID 和项目 ID。

与其他 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 connectors、Perplexity，……）需要 HTTPS MCP URL，且无法运行本地命令，因此不能直接添加此 stdio 构建。

使用示例

• “查找海岸线的 4K 无人机视频，时长不超过 30 秒” → search_videos { keywords: "coastline aerial", quality: "4K", max_duration: 30 }
• “用于产品视频的欢快纯音乐，约 120 BPM” → 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 是公开的，可以放心保留。
• 图片 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 在客户端分页（每页 50 条，使用 search 筛选），因为 Storyblocks 会在单个响应中返回整个列表——数百条内容。get_stock_items_details_batch 默认会获取并合并所有上游分页结果，因此 invalid_stock_ids / stock_ids_not_found 始终完整（Storyblocks 仅在最后一页报告这些信息）。

用户和项目 ID

Storyblocks 要求每次搜索和下载都提供 user_id 和 project_id。它们是你自己的系统中的标识符——Storyblocks 不会签发这些标识符，其控制面板也不会显示它们——它们的作用是让 Storyblocks 将下载与搜索关联起来、重现支持案例，并在向贡献者付款时对同一人重复下载进行去重。由于最后这一点，user_id 必须长期保持稳定，且不能是姓名或邮箱（原始值会被传输；Storyblocks 会在其一侧对其进行哈希处理）。

个人安装无需配置。服务使用：

	默认值	来源
project_id	storyblocks-mcp	标识此集成的固定 slug
user_id	mcp- + 16 个随机十六进制字符	使用 crypto.randomBytes 生成一次，并保存到 ~/.storyblocks-mcp/user-id，因此重启后仍保持稳定，且每次安装都不同

如果你将此服务嵌入到已有用户和项目 ID 的多用户应用中，请设置 STORYBLOCKS_DEFAULT_USER_ID / STORYBLOCKS_DEFAULT_PROJECT_ID，或在每次调用时传入 user_id / project_id。两者都必须匹配 ^[A-Za-z0-9_-]+$——服务会在启动时（环境变量）或发送请求前（工具参数）拒绝任何其他值。它绝不会根据你的主机名、操作系统用户名或邮箱推导 ID。STORYBLOCKS_STATE_DIR 可更改状态文件的位置。

身份验证的工作方式

每个请求都携带三个查询参数：APIKEY（你的公钥）、EXPIRES（Unix 时间戳，最多提前 36 小时）以及 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 消息，以及针对该响应提供的故障排除提示。403 错误且消息为 "APIKEY header is invalid" 表示密钥错误或系统时钟偏差；403 错误且消息为 "API function request is invalid." 表示你的密钥尚未启用该端点。

构建

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/*），因此在 server/index.js 中手动实现，比依赖 SDK 更简单。

贡献

参见 CONTRIBUTING.md。

许可证

MIT © Kyle Renfrow

---

与 Storyblocks 无关，也未获其认可。“Storyblocks”是 Footage Firm, Inc. 的商标。使用 Storyblocks API 须遵守你与 Storyblocks 签订的 API 协议。