Etchv

Etchv MCP 服务

这是一个本地 stdio Model Context Protocol 服务， 可让 AI 助手使用 Etchv 为图像、PDF 和视频添加水印并检测水印。

要求

• Node.js 24 或更高版本
• Etchv API 密钥，仅需包含你需要的作用域
• 用于输入和输出文件的现有目录

配置

变量	必需	说明
ETCHV_API_KEY	是	Etchv API 密钥。请将其保存在客户端的密钥或环境变量配置中，切勿放入聊天中。
ETCHV_FILES_ROOT	是	现有目录的绝对路径。所有输入和输出文件都必须位于该目录中。
ETCHV_API_BASE_URL	否	API 源站。默认为 https://api.etchv.com。
ETCHV_LARGE_FILE_THRESHOLD	否	超过此字节数的文件会上传一次到签名 URL，并通过 ID 发送。默认为 40 MiB。

Claude Code

claude mcp add etchv --scope user \
  -e ETCHV_API_KEY="$ETCHV_API_KEY" \
  -e ETCHV_FILES_ROOT="$HOME/etchv-media" \
  -- npx -y @etchv-labs/mcp-server@1

编辑器插件

此仓库也是一个 Cursor 插件（.cursor-plugin/plugin.json 和 mcp.json）以及 Gemini CLI 扩展（gemini-extension.json）。两者都运行同一 软件包，并且需要 ETCHV_API_KEY 和 ETCHV_FILES_ROOT。Gemini CLI 会在安装时 提示你提供这些值；在 Cursor 中，请在 Plugins 下设置，然后选择 Configure：

gemini extensions install https://github.com/etchv-labs/mcp-server

Claude Desktop、Cursor 和其他 mcpServers 客户端

将以下内容添加到客户端的 MCP 配置中（例如 claude_desktop_config.json 或 ~/.cursor/mcp.json），然后重启客户端：

{
  "mcpServers": {
    "etchv": {
      "command": "npx",
      "args": ["-y", "@etchv-labs/mcp-server@1"],
      "env": {
        "ETCHV_API_KEY": "YOUR_ETCHV_API_KEY",
        "ETCHV_FILES_ROOT": "/absolute/path/to/etchv-media"
      }
    }
  }
}

然后让助手运行 check_api_key，以确认连接正常。

工具

工具	功能	所需作用域
check_api_key	显示组织 ID、密钥 ID 和作用域；不消耗额度	任意有效密钥
watermark_media	为文件添加水印，支持同步或异步；消耗额度	watermarks:embed（链接需 assets:read）
detect_media	检测水印，支持同步或异步；消耗额度	watermarks:detect
create_upload	创建上传会话并返回签名上传 URL	watermarks:embed；用于 detect 时需 watermarks:detect
get_job、get_job_result	读取任务状态；获取已完成的结果	对应的 embed/detect 作用域
watermark_batch	在一个批次中为最多 100 个本地文件添加水印，每个文件使用各自的数据；消耗额度	watermarks:embed
get_batch、download_batch	跟踪批次；保存每个结果或批次的 zip 文件	watermarks:embed
list_assets、get_asset、download_asset	列出、检查、下载资源或获取资源链接	assets:read
update_asset	重命名或替换元数据（需进行版本检查）	assets:write
delete_asset	删除资源	assets:delete，所有者/管理员
create_link	分享源资源，让每位接收者都能打开自己的水印副本；复制会消耗额度	links:write
list_links、get_link	列出链接；读取链接及每位接收者的打开记录和副本	links:read
revoke_link	停止通过链接进行新的打开和下载	links:write
delete_link、remove_link_recipient	删除链接或某位接收者及其打开记录、下载记录和副本；此操作无法撤销	links:write、assets:delete，所有者/管理员
list_storage_destinations、list_storage_deliveries、get_storage_delivery	检查客户存储	storage:read
verify_storage_destination、store_asset、retry_storage_delivery	测试存储桶；交付或重试结果	storage:write，所有者/管理员
list_webhooks、list_webhook_deliveries	检查 webhook 端点和交付记录	webhooks:read
redeliver_webhook	重新发送现有事件	webhooks:write，所有者/管理员

每个工具都有标题，以及 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint 注释。

输入和输出

watermark_media 和 detect_media 接受以下文件输入，且只能选择其中一种：

• input_path：位于 ETCHV_FILES_ROOT 内的本地文件。
• input_url：公开的 HTTPS URL。服务端会下载该文件，并像处理本地文件一样提交。请参阅 安全性，了解适用的检查。文件名取自 Content-Disposition 标头，否则取自 URL 路径；传入 filename 可设置文件名。文件扩展名必须与 media 匹配。
• upload_id：来自 create_upload 的 upl_ ID。能够自行发送文件的客户端会调用 create_upload，并传入 kind（image、document、video，或用于检查已交付文件的 detect）、filename 和精确的字节数 size，然后在不使用 API 密钥的情况下，将字节 PUT 到返回的 upload.url，最后传入 upload_id。上传只能使用一次，并会在 24 小时后过期。
• asset_id：现有资源，例如要检查的已交付文件。服务端会下载并重新提交该文件。也可在此处通过 filename 覆盖其名称。

如果提供了 output_path，带水印的文件会保存到该路径（适用于同步调用的 watermark_media、get_job_result 和 download_asset）。如果未提供 output_path，这些工具会返回结果的 asset_id 和元数据，其中包含 download_url 和 download_expires_at：一个 15 分钟内无需 API 密钥即可使用的链接。任何拥有该链接的人都可以下载文件，因此只应将它分享给需要该文件的人。创建链接需要 assets:read 范围；如果创建失败，错误会指出资源名称，以便你在密钥获得相应权限后调用 download_asset。

提交操作需要稳定的 idempotency_key；重试时请重复使用该值，以免重复扣费。图像和 PDF 上传大小上限为 50 MiB，DOCX、PPTX 和视频上传大小上限为 20 MiB。PDF 页数必须为 1 至 2,000 页，带水印的副本必须小于 95 MiB 加上每页 48 KiB，因此 2,000 页的 PDF 最大约为 1 MiB。检测会处理 Etchv 交付的文件：图像上限为 192 MiB，PDF 上限为 95 MiB，DOCX、PPTX 和视频上限为 100 MiB。超过 40 MiB 的文件会自动通过上传会话处理；超过 95 MiB 的图像或文档检测会返回作业回执，需通过 get_job_result 获取结果。存储目标和 webhook 端点需在控制面板中创建，不能通过此服务端创建。

watermark_media 和 detect_media 接受可选的 accelerator（cpu 为默认值，也可选择 gpu）。GPU 处理需要 Business 或 Enterprise 套餐，且会消耗 3 倍额度；如果没有可用的 GPU，作业会以正常额度在 CPU 上运行。结果会通过 accelerator 报告实际使用的硬件，get_job 还会返回 accelerator_requested。watermark_media 和 watermark_batch 还接受 PDF 的 active_content：keep（默认值）会按上传时的状态返回脚本和操作；remove_auto_run 会移除 PDF 查看器自动运行的内容，例如打开操作、文档级 JavaScript 和 XFA 表单。在批量处理中，remove_auto_run 要求所有文件都是 PDF。达到速率或并发限制时，错误会包含 retry_after_seconds，并指向套餐升级页面。Trial 和 Launch 套餐一次只能运行一个操作。

批次

watermark_batch 最多可处理 100 个文件，文件可通过以下三种方式指定：input_paths、带可选 glob 的 input_dir（例如 "contracts/*.pdf"；不允许使用花括号和 ..），或包含各自 data 的 items。data_template 会为每个文件填入数据；字符串值可使用 {filename}、{stem} 和 {index}（文件从 0 开始的位置）。服务会创建批次，将每个文件上传一次到其签名 URL（不带 API 密钥），然后启动批次。设置 wait: true 时，服务会按照 API 要求的频率轮询，最长等待 wait_seconds（默认值为 600），在客户端要求时发送进度通知，并通过 output_dir 保存结果。否则，请调用 get_batch，然后调用 download_batch：该工具会将每个成功处理的文件按其在批次 zip 中的名称保存（NNN-<name>-watermarked.<ext>）；如果创建批次时设置了 archive: true，则会保存为单个 zip，并列出失败项目及其错误代码。每个文件的费用与单次请求相同，失败的文件会退款。使用相同参数重试会恢复或返回同一批次；如果该批次未启动便已过期，或其结果已过期，该工具会要求提供新的 idempotency_key。

托管模式

etchv-mcp 命令始终以本地模式运行。src/server.ts 中的 createServer 也接受 mode: "hosted"，用于运行在远程且无法访问用户文件的服务。托管模式下无需设置 filesRoot；所有工具的架构中都会省略 input_path、output_path 和其他本地文件参数；不提供 watermark_batch 和 download_batch；结果以下载链接的形式返回；服务说明和 etchv://capabilities 也会描述此模式。

安全

• API 密钥仅读取自 ETCHV_API_KEY，只会发送到已配置的源站，且绝不会出现在工具参数、结果、错误或日志中。
• 文件访问仅限于 ETCHV_FILES_ROOT：拒绝路径遍历和符号链接，且绝不覆盖已有文件。
• 仅接受 HTTPS API 源站（仅 localhost 可使用 HTTP），且绝不跟随 API 重定向。
• input_url 必须使用 HTTPS，且不能包含用户名或密码。主机只能解析为公共地址：拒绝环回、私有、链路本地、运营商级 NAT、多播、保留和文档地址范围，包括嵌入此类 IPv4 地址的 IPv6 地址形式。连接使用经过检查的地址，最多跟随 3 次重定向且每次都会重新检查；下载大小受操作上传限制约束，并设有超时；绝不会将 API 密钥发送到此 URL。
• API 响应、资源名称和元数据均视为不可信数据，绝不视为指令。

链接

• 指南：https://etchv.com/docs/mcp?utm_source=mcp-local&utm_medium=readme&utm_campaign=integrations
• API 参考：https://etchv.com/docs?utm_source=mcp-local&utm_medium=readme&utm_campaign=integrations
• 问题反馈：https://github.com/etchv-labs/mcp-server/issues
• 支持：[email protected]

如有疑问或需要报告错误，请在此处提交问题，或发送邮件至 [email protected]。

许可证

MIT