Dropl MCP

Dropl MCP

通过 Cursor 或 Claude Code 创建客户端可编辑的照片和视频图库，然后进行嵌入。

Dropl MCP 可让 AI 编码 Agent 为客户端网站配置 Dropl：创建客户端站点和展示集（可嵌入的照片和视频图库），按类别上传整个媒体文件夹，为 HTML、Next.js、WordPress、Webflow 和 Framer 获取嵌入代码，管理菜单、库存和活动等集合，并通过在代码中修复客户端反馈、回复反馈并将其标记为已完成来处理反馈。随后，客户端无需使用 CMS，即可通过手机更新自己的照片和视频。

这是一个用于 Dropl 的 MCP 服务，为使用代码或 WordPress、Webflow 和 Framer 构建客户端网站的人提供客户端可编辑的图库、面向代理机构的视频托管（无广告的 Vimeo 替代方案）和客户端反馈。上传内容会直接从你的电脑传到 Dropl 的存储空间，支持断点续传，并且可以安全地重复运行。Agent 会先向你展示计划，并在创建任何内容或上传文件前征求你的确认。

安装

也可以手动添加：参见客户端配置。需要 Node.js 20.3 或更高版本。无需安装：你的 MCP 客户端会通过 npx 运行它。

然后在终端中登录一次。这会打开浏览器，供你批准访问；密钥会保存在这台电脑上。

npx -y @dropl/mcp login

可以提出的请求

• “将 ./assets/portfolio 中的照片上传到一个新的 Dropl 展示集，供这个客户端使用，并为每个文件夹创建一个筛选标签页。”
• “将该展示集嵌入 Work 页面。”
• “我已将 Vimeo 视频下载到 ~/vimeo-export。将它们移到 Dropl，并把 Vimeo 嵌入内容换成 Dropl 的。”
• “将此网站上的菜单改成客户端可以编辑的 Dropl 集合。”
• “修复此网站尚未处理的 Dropl 反馈。”
• “为 Projects 展示集中缺少替代文本的照片撰写替代文本。”
• “这个客户端还剩多少存储空间和带宽？”

Agent 会先制定计划，并在创建内容、上传文件或更改集合字段前征求确认。

身份验证

选择一种方式：

• 浏览器登录（推荐）： npx -y @dropl/mcp login。它会显示一个代码，打开 Dropl 批准页面，并保存生成的 API 密钥。使用 --client "Cursor" 为其添加标签，使用 --no-browser 只打印链接，使用 --api-url 指定非生产环境的 API。
• API 密钥： 在 Dropl → Settings → API keys 中创建密钥，并将其设置为 MCP 服务环境中的 DROPL_API_KEY。设置后，该密钥的优先级高于已保存的登录凭据。

只有账户所有者和管理员可以批准登录或创建 API 密钥。密钥可以限制为特定客户端站点和权限范围。

其他命令：

npx -y @dropl/mcp whoami    # show the connected account and key
npx -y @dropl/mcp logout    # remove the saved key from this computer

logout 只会删除本地副本。要停用密钥，请在 Dropl → Settings → API keys 中撤销它。

客户端配置

Cursor

在 .cursor/mcp.json（当前项目）或 ~/.cursor/mcp.json（所有项目）中配置：

{
  "mcpServers": {
    "dropl": {
      "command": "npx",
      "args": ["-y", "@dropl/mcp@latest"]
    }
  }
}

使用 API 密钥而非浏览器登录：

{
  "mcpServers": {
    "dropl": {
      "command": "npx",
      "args": ["-y", "@dropl/mcp@latest"],
      "env": { "DROPL_API_KEY": "dropl_live_…" }
    }
  }
}

不要提交包含密钥的配置文件。请使用用户级别的 ~/.cursor/mcp.json，或将项目配置文件排除在版本控制之外。

Claude Code

claude mcp add dropl -- npx -y @dropl/mcp@latest

使用 API 密钥：

claude mcp add dropl -e DROPL_API_KEY=dropl_live_… -- npx -y @dropl/mcp@latest

其他 MCP 客户端

使用 stdio 服务，命令为 npx，参数为 ["-y", "@dropl/mcp@latest"]。如果不使用浏览器登录，请将 DROPL_API_KEY 添加到其环境变量中。

工具

工具	功能
plan_migration	扫描本地文件夹，不会上传任何内容。返回每个文件夹中的照片和视频数量及大小、不支持的文件、建议的类别以及运行步骤。使用 layout: "projects"（或包含项目文件夹的 projects/ 文件夹）时，会为每个文件夹规划一个项目，并提供其标题、slug 和数量。
whoami	已连接的账户、用户、角色、密钥名称／前缀、范围和站点限制。
list_sites / create_site	列出客户站点，或创建站点（名称、可选域名）。
list_showcases / create_showcase	列出站点的作品集及其类型和项目数量，或创建作品集（标题、type 为 gallery 或 projects、布局、网格适配方式、类别筛选条件、页面大小）。
get_showcase / update_showcase	汇总作品集（按状态和类别划分的项目、照片、缺少替代文本的照片及失败项），或更改其设置。
list_showcase_items	分页列出作品集项目：id、类型、状态、文件名、上传文件的本地路径、替代文本和类别。可按类型、是否缺少替代文本、类别或文本筛选。
update_items	在一次调用中，根据上传时返回的 id 为多个项目设置替代文本并添加或移除类别（也适用于媒体库视频 id）。不存在的类别会自动创建。
create_category	向作品集添加类别；如果已有同名类别，则会复用。
tag_items	根据上传时返回的 id，为作品集项目添加或移除类别。
upload_photos	将文件、文件夹或 glob 匹配的照片上传到作品集，可为每张照片（files）设置替代文本和类别。也可根据文件夹创建类别。在 projects 作品集中，传入 project 可将照片上传到该项目。支持试运行和续传。返回每个文件对应的作品集项目 id。
list_videos	列出站点的视频。
upload_videos	将视频分段并以可续传方式上传到站点的媒体库，也可选择将其添加到作品集并设置类别（或通过 project 添加到其中一个项目）。返回每个文件对应的视频 id（和作品集项目 id）。
add_videos_to_showcase	将媒体库中已有的视频添加到作品集或其中一个项目。
get_embed_code	获取视频或作品集（或其中一个类别或项目）的嵌入代码片段，以及如何将其粘贴到 HTML、React/Next.js、WordPress、Webflow 和 Framer 中。对于 projects 作品集，projectUrl（例如 /work/{slug}）可将索引卡片链接到每个项目对应的页面。
list_projects	按顺序列出 projects 作品集的项目（摘要、详细信息、类别、数量），或列出单个项目的完整描述及其照片和视频。
create_project / update_project	添加项目（标题、副标题、描述、slug、详细信息、类别），或修改项目，包括其封面。同名或同 slug 的现有项目会被复用。
reorder_projects / reorder_project_items	设置项目顺序，或设置单个项目内照片和视频的顺序。部分列表中的项目会排在前面；其余项目保持原有顺序。
get_project_details	获取 projects 作品集的自定义详细信息（例如位置或年份等字段）及其 version，包括在控制面板中所做的编辑。
plan_project_details / apply_project_details	预览项目详细信息变更但不保存，然后使用读取到的 expectedVersion 应用变更。键永不更改；移除值需要 confirmDestructive。
get_usage	查看已用存储空间和带宽占套餐限额的情况，以及上传是否已暂停。
list_collections	列出站点的集合（菜单、库存、活动），包括项目数量和套餐限额。
get_collection_schema	获取集合当前的字段和 schemaVersion，包括在控制面板中所做的编辑。
plan_collections / apply_collection_plan	以纯文本差异形式预览集合的创建或修改，然后应用变更。破坏性变更需要 confirmDestructive；基于过期架构制定的计划会被拒绝。
add_collection_items	批量添加项目，并提供每个项目的错误信息。默认进行试运行；重试不会重复添加。
list_collection_items	列出项目，支持搜索、状态和字段筛选、排序及分页。
get_collection_code	获取集合的 TypeScript 类型和 Next.js 获取示例。
undo_collection_change	在不会丢失数据的情况下撤销最近一次架构变更。
list_feedback	查看客户在站点上留下的反馈（评论、文本修改、备注）。默认筛选待处理和进行中的反馈；可按状态、类型和页面筛选。
get_feedback	获取一条请求及其完整上下文：页面、点击的元素（选择器和文本）、设备、截图和照片，以及讨论串。
reply_to_feedback	在请求的讨论串中回复，例如请客户进一步说明。系统会向客户发送邮件；重试不会重复发帖。
update_feedback_status	将状态设为待处理、进行中、已完成或不予处理，并附上简短备注。标记为已完成时会向客户发送邮件。
读取 Collections 需要具有 collections:read 权限范围的 API 密钥；添加项目需要 collections:write；创建或更改集合需要 collections:schema。

读取 Feedback 需要 feedback:read，回复或更改状态需要 feedback:write。Feedback 推出前创建的密钥不包含这些权限范围；请再次运行 npx -y @dropl/mcp login 获取新密钥。让你的 Agent “修复未解决的 Dropl 反馈”：它会读取每条请求，在代码中应用文本修改；遇到不清楚的地方时询问客户端，并将已修复的请求标记为已完成。

上传结果、ID 和替代文本

upload_photos 和 upload_videos 会返回一个 files 列表，将每个本地路径映射到对应的 Dropl ID，并标注状态：uploaded、already_uploaded（重跑时跳过，包含 ID）、failed（附带 error）或 pending（试运行）。列表最多显示前 100 个；omitted 和 more 会说明如何使用 list_showcase_items 分页查看其余项目。

{
  "uploaded": 2,
  "alreadyUploaded": 1,
  "altTextSet": 2,
  "files": {
    "count": 3,
    "items": [
      { "path": "Decks/cedar.jpg", "id": "0190…a1", "status": "uploaded" },
      { "path": "Decks/railing.jpg", "id": "0190…a2", "status": "uploaded" },
      { "path": "kitchen.jpg", "id": "0190…a0", "status": "already_uploaded" }
    ],
    "omitted": 0,
    "more": null
  }
}

上传时可为每张照片设置替代文本和类别：

{
  "showcaseId": "…",
  "files": [
    { "path": "/abs/photos/cedar.jpg", "alt": "Cedar deck with glass railing at dusk", "categories": ["Decks"] },
    { "path": "/abs/photos/texture.jpg", "alt": "" }
  ]
}

也可以稍后使用 update_items 设置，无需重新上传：{ "showcaseId": "…", "items": [{ "id": "0190…a1", "alt": "黄昏时的雪松木平台", "addCategories": ["Decks"] }] }。替代文本应简洁、描述性强（说明照片展示的内容，不要写“图片显示”），纯装饰性照片则留空。替代文本最多为 500 个字符。更改替代文本需要 showcases:write 权限范围。

支持上传：JPEG、PNG、WebP、AVIF 和 HEIC 格式的照片，每张不超过 20 MB；系统会同时根据文件内容和扩展名进行检查。视频格式包括 MP4、MOV、WebM、MKV、AVI、MPEG 和 M4V。隐藏文件会被跳过。不会跟随指向待上传文件夹之外的符号链接。

环境变量

变量	用途
DROPL_API_KEY	用此 API 密钥代替已保存的登录信息。
DROPL_API_URL	API 基础 URL。默认为 https://www.dropl.io/api。仅当地址为 localhost/127.0.0.1 时才接受纯 http://，例如本地开发时使用 http://localhost:3000/api。

安全性

• 保存的密钥位于 ~/.config/dropl/credentials.json（如果已设置 $XDG_CONFIG_HOME，则位于 $XDG_CONFIG_HOME/dropl；Windows 上位于 %APPDATA%\dropl）。文件夹以 0700 模式创建，文件以 0600 模式原子写入。如果其他用户可以读取该文件，服务将拒绝读取。
• 密钥不会完整显示；只显示其前缀（例如 dropl_live_ab12…）。系统会告知 Agent，绝不要要求你在聊天中粘贴密钥。
• 密钥只会通过 HTTPS 发送到已配置的 Dropl API，且绝不会跟随重定向。文件通过短期有效的签名 URL 上传到存储服务；你的密钥绝不会发送到存储服务。
• 为了恢复中断的上传，上传进度会以小型清单形式保存在 ~/.config/dropl/uploads/。清单记录文件路径和 Dropl ID，不会记录文件内容。
• 你可以随时在 Dropl → Settings → API keys 中撤销任何密钥。

常见问题

免费吗？ MCP 服务免费且开源（MIT）。它需要 Dropl 账户；新账户可免费试用，无需信用卡，定价按客户端网站收费，而非按席位收费。请参阅定价。

我的客户端需要账户吗？ 只有在需要编辑时才需要。通过 Dropl → Settings → Sites 邀请客户端，他们就会获得一个客户端门户，其中只显示他们的网站；他们可以用手机更新自己的照片和视频、编辑合集以及提出修改请求。这是面向客户端网站的 CMS 替代方案：无需学习，他们也永远不会接触代码。网站访客无需任何东西。

哪些网站构建工具适用？ 任何支持嵌入代码或脚本标签的工具都适用。get_embed_code 会返回照片图库嵌入代码或视频播放器，并提供适用于纯 HTML、React 和 Next.js、WordPress、Webflow 以及 Framer 的粘贴说明，因此同一个作品展示可以作为 Webflow 图库或 Framer 图库使用。对于用代码编写的网站，合集也会以 JSON 格式提供：无需运行 CMS，即可为 Next.js 提供无头媒体。

文件存储在哪里？ 存储在你的 Dropl 账户中。上传文件会通过短期有效的签名 URL，直接从你的计算机传输到 Dropl 的存储空间，嵌入内容也会从那里提供。在你的计算机上，服务只保存登录密钥和一份简短的上传日志（请参阅安全性）。

要录制的演示

在演示录制完成前，先保留上面的占位内容。录制分辨率约为 1280×800，每段控制在 30 秒以内，并保存到 docs/media/。npm 不会打包该文件夹，因此请使用公共仓库中的绝对 URL 链接到这些文件（例如，https://raw.githubusercontent.com/<owner>/<repo>/main/docs/media/fix-feedback.gif），这样它们也会显示在 npm 上：

1. fix-feedback.gif：在 Cursor 中输入“修复此网站未处理的 Dropl 反馈”。展示 Agent 列出请求、编辑代码、回复一条不明确的请求，并将其余请求标记为已完成，然后展示客户端门户中这些请求已显示为完成。
2. folder-to-embed.gif：输入“将 ./assets/portfolio 上传到新的作品展示，并将其嵌入 Work 页面”。展示计划和确认、上传进度、粘贴到页面中的嵌入代码，以及浏览器中带筛选标签的图库。