Etchv

io.github.etchv-labsPublished by GitHub account etchv-labsv1.6.0Updated Oct 29, 2026

Invisible watermarking and watermark detection for images, PDFs and videos with Etchv.

VerifiedSTDIODesktop onlyFiles & StorageMedia & Design

Overview

AI-generated overview

Local stdio MCP server that lets an assistant apply invisible watermarks to images, PDFs and videos and detect them, using the Etchv API.

What you can do
  • Watermark or detect a watermark in a single image, PDF, DOCX, PPTX or video, synchronously or as a job
  • Run batches of up to 100 local files with per-file data templates, then follow and download results
  • Create upload sessions and pass files by upload ID, public HTTPS URL or existing asset ID
  • List, inspect, download, rename, update or delete assets, and create or revoke shareable links
  • Inspect storage destinations and deliveries, and list or redeliver webhook events
  • Check the API key's organization, key ID and scopes
When to use it
Useful when you want an assistant to embed invisible watermarks in media you own or to check whether delivered files carry one, including bulk runs over a folder of contracts or images, without leaving the chat client.
Requirements
Node.js 24 or later, run via npx. Requires an Etchv API key in ETCHV_API_KEY with the scopes needed, and an absolute path to an existing directory in ETCHV_FILES_ROOT that all input and output files must stay inside. ETCHV_API_BASE_URL is optional and defaults to the Etchv API origin. Network access to the Etchv API.
Before you install
Watermarking, detection, batch runs and link copies spend Etchv credits; GPU processing needs a Business or Enterprise plan and costs 3x credits. Delete and revoke tools are irreversible, and storage and webhook actions need owner or admin rights. Download links returned without output_path work without an API key for 15 minutes, so anyone holding one can fetch the file. Keep ETCHV_API_KEY in the client's secret config, not in chat.

Installation

In SourceWeft

  1. Open Etchv in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Etchv MCP server

A local stdio Model Context Protocol server that lets AI assistants watermark and detect images, PDFs and videos with Etchv.

Requirements

  • Node.js 24 or later
  • An Etchv API key with only the scopes you need
  • An existing directory for input and output files

Configuration

VariableRequiredDescription
ETCHV_API_KEYYesEtchv API key. Keep it in your client's secret or env config, never in chat.
ETCHV_FILES_ROOTYesAbsolute path of an existing directory. All input and output files must be inside it.
ETCHV_API_BASE_URLNoAPI origin. Defaults to https://api.etchv.com.
ETCHV_LARGE_FILE_THRESHOLDNoFiles above this many bytes are uploaded once to a signed URL and sent by ID. Defaults to 40 MiB.

Claude Code

sh
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

Editor plugins

This repository is also a Cursor plugin (.cursor-plugin/plugin.json with mcp.json) and a Gemini CLI extension (gemini-extension.json). Both run the same package and need ETCHV_API_KEY and ETCHV_FILES_ROOT. Gemini CLI asks for them at install; in Cursor, set them under Plugins, then Configure:

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

Claude Desktop, Cursor and other mcpServers clients

Add this to the client's MCP config (for example claude_desktop_config.json or ~/.cursor/mcp.json) and restart it:

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"      }    }  }}

Then ask the assistant to run check_api_key to confirm the connection.

Tools

ToolWhat it doesKey scope
check_api_keyShow organization ID, key ID and scopes; no creditsAny valid key
watermark_mediaWatermark a file, sync or async; spends creditswatermarks:embed (assets:read for links)
detect_mediaDetect a watermark, sync or async; uses creditswatermarks:detect
create_uploadCreate an upload session and return its signed upload URLwatermarks:embed, or watermarks:detect for detect
get_job, get_job_resultRead job status; collect a finished resultMatching embed/detect scope
watermark_batchWatermark up to 100 local files in one batch, each with its own data; spends creditswatermarks:embed
get_batch, download_batchFollow a batch; save each result or the batch's zipwatermarks:embed
list_assets, get_asset, download_assetList, inspect, download or link to assetsassets:read
update_assetRename or replace metadata (version-checked)assets:write
delete_assetDelete an assetassets:delete, owner/admin
create_linkShare a source asset so each recipient opens their own watermarked copy; copies spend creditslinks:write
list_links, get_linkList links; read one with each recipient's opens and copylinks:read
revoke_linkStop new opens and downloads of a linklinks:write
delete_link, remove_link_recipientDelete a link, or one recipient, with their opens, downloads and copies; can't be undonelinks:write, assets:delete, owner/admin
list_storage_destinations, list_storage_deliveries, get_storage_deliveryInspect customer storagestorage:read
verify_storage_destination, store_asset, retry_storage_deliveryTest a bucket; deliver or retry a resultstorage:write, owner/admin
list_webhooks, list_webhook_deliveriesInspect webhook endpoints and deliverieswebhooks:read
redeliver_webhookResend an existing eventwebhooks:write, owner/admin

Every tool has a title and readOnlyHint, destructiveHint, idempotentHint and openWorldHint annotations.

Inputs and outputs

watermark_media and detect_media take the file as exactly one of:

  • input_path: a local file inside ETCHV_FILES_ROOT.
  • input_url: a public HTTPS URL. The server downloads it and submits it like a local file. See Security for the checks it applies. The file name comes from the Content-Disposition header, else the URL path; pass filename to set it. Its extension must match media.
  • upload_id: an upl_ ID from create_upload. A client that can send files itself calls create_upload with kind (image, document, video, or detect to check a delivered file), filename and the exact size in bytes, PUTs the bytes to the returned upload.url without an API key, then passes upload_id. An upload is used once and expires after 24 hours.
  • asset_id: an existing asset, such as a delivered file to check. The server downloads it and submits it again. filename can override its name here too.

A watermarked file is saved to output_path when one is given (sync watermark_media, get_job_result and download_asset). Without output_path, these tools return the result's asset_id and metadata with download_url and download_expires_at: a link that works without an API key for 15 minutes. Anyone with the link can download the file, so share it only with the person who needs it. Creating a link needs the assets:read scope; if it fails, the error names the asset so you can call download_asset once the key allows it.

Submissions require a stable idempotency_key; reuse it when retrying so you are not charged twice. Image and PDF uploads are limited to 50 MiB and DOCX, PPTX and video uploads to 20 MiB. A PDF has 1 to 2,000 pages, and its watermarked copy must fit in 95 MiB with 48 KiB per page, so a 2,000-page PDF can be up to about 1 MiB. Detection takes the files Etchv delivered: up to 192 MiB for images, 95 MiB for PDFs and 100 MiB for DOCX, PPTX and video. Files over 40 MiB go through an upload session automatically, and image or document detection above 95 MiB returns a job receipt to collect with get_job_result. Storage destinations and webhook endpoints are created in the dashboard, not through this server.

watermark_media and detect_media accept an optional accelerator (cpu, the default, or gpu). GPU processing requires a Business or Enterprise plan and costs 3× credits; if no GPU is ready, the job runs on CPU at normal credits. Results report the hardware actually used as accelerator, and get_job also returns accelerator_requested. watermark_media and watermark_batch also accept active_content for PDFs: keep (the default) returns scripts and actions as uploaded, and remove_auto_run removes what a PDF viewer runs by itself, such as open actions, document-level JavaScript and XFA forms. In a batch, remove_auto_run needs every file to be a PDF. When a rate or concurrency limit is reached, errors include retry_after_seconds and point to the plan upgrade page. Trial and Launch plans run one operation at a time.

Batches

watermark_batch takes up to 100 files, named one of three ways: input_paths, input_dir with an optional glob (for example "contracts/*.pdf"; braces and .. are refused), or items with their own data. A data_template fills in each file's data; string values may use {filename}, {stem} and {index} (the file's 0-based position). The server creates the batch, uploads each file once to its signed URL without the API key, and starts it. With wait: true it polls at the pace the API asks for, for up to wait_seconds (default 600), sending progress notifications when the client asks for them, and with output_dir saves the results. Otherwise call get_batch, then download_batch, which saves each successful file under its name in the batch zip (NNN-<name>-watermarked.<ext>), or the single zip when the batch was created with archive: true, and lists failed items with their error codes. Each file costs the same credits as a single request, and files that fail are refunded. Retrying with the same arguments resumes or returns the same batch; if that batch expired unstarted or its results have expired, the tool asks for a new idempotency_key.

Hosted mode

The etchv-mcp command always runs in local mode. createServer in src/server.ts also takes mode: "hosted" for a server that runs remotely and has no access to the user's files. In hosted mode no filesRoot is needed; input_path, output_path and the other local file arguments are left out of every tool schema; watermark_batch and download_batch are not offered; results are returned as download links; and the server instructions and etchv://capabilities describe that mode.

Security

  • The API key is read only from ETCHV_API_KEY, sent only to the configured origin, and never appears in tool arguments, results, errors or logs.
  • File access is confined to ETCHV_FILES_ROOT: traversal and symlinks are rejected, and existing files are never overwritten.
  • Only HTTPS API origins are accepted (HTTP for localhost only), and API redirects are never followed.
  • input_url must be HTTPS without a user name or password. The host must resolve only to public addresses: loopback, private, link-local, carrier-grade NAT, multicast, reserved and documentation ranges are refused, including IPv6 forms that embed such an IPv4 address. The connection uses the checked address, at most 3 redirects are followed and each is checked again, the download is capped at the operation's upload limit and times out, and the API key is never sent to the URL.
  • API responses, asset names and metadata are treated as untrusted data, never instructions.

Links

Questions or bug reports: open an issue here or email [email protected].

License

MIT

Source: README.md at commit 0f2f162

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the server did not start.

Version history

1
  1. v1.6.0LatestOct 29, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts