Lets an AI assistant watermark and detect invisible watermarks in images, PDFs, and videos.
Also known as etchv-labs/mcp-server, mcp-server, @etchv-labs/mcp-server
- Stars
- 0
- Tools
- 14
- Downloads, 30 days
- 1,329
- Latest version
- 1.6.0
- Last commit
- Oct 29, 2026
- License
- MIT
What is Etchv MCP?
Etchv lets an AI assistant watermark and detect invisible watermarks in images, PDFs, and videos. It exposes 14 tools, such as check_api_key, watermark_media, detect_media.
Summary generated from the project's README
About Etchv MCP server
Adding invisible watermarks to media files from within an AI assistant is what Etchv enables for developers and content creators. This local stdio server allows users to embed or detect watermarks in images, PDFs, and videos using the Etchv API. It works by connecting to a local directory defined by the ETCHV_FILES_ROOT variable, ensuring all file operations remain confined to a specific path on your machine.
To use the server, you must provide an ETCHV_API_KEY and have Node.js 24 or later installed. The server supports various workflows, including single file processing with watermark_media and detect_media, or high-volume tasks using watermark_batch for up to 100 files at once. It can handle large files by automatically using signed upload URLs for anything exceeding 40 MiB. Users can also manage assets, create shareable links, and monitor job statuses through specialized tools like get_job and download_batch.
What you can do with it
- 1Securely share watermarked assetsGenerate a temporary link so a recipient can download their own watermarked copy of a file.
- 2Sanitize PDF documentsRemove automatic scripts and JavaScript from a PDF while applying a watermark.
Written from the project's README. Every use case is checked against a quote from it.
How to install Etchv MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Etchv MCP in Claude Code
$ claude mcp add --env 'ETCHV_API_KEY=<YOUR_ETCHV_API_KEY>' --env 'ETCHV_FILES_ROOT=<ETCHV_FILES_ROOT>' mcp-server -- npx -y @etchv-labs/mcp-serverInstall Etchv MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@etchv-labs/mcp-server"
],
"env": {
"ETCHV_API_KEY": "<YOUR_ETCHV_API_KEY>",
"ETCHV_FILES_ROOT": "<ETCHV_FILES_ROOT>"
}
}
}
}Install Etchv MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@etchv-labs/mcp-server"
],
"env": {
"ETCHV_API_KEY": "<YOUR_ETCHV_API_KEY>",
"ETCHV_FILES_ROOT": "<ETCHV_FILES_ROOT>"
}
}
}
}Install Etchv MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@etchv-labs/mcp-server"],"env":{"ETCHV_API_KEY":"<YOUR_ETCHV_API_KEY>","ETCHV_FILES_ROOT":"<ETCHV_FILES_ROOT>"}}'Install Etchv MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@etchv-labs/mcp-server"
],
"env": {
"ETCHV_API_KEY": "<YOUR_ETCHV_API_KEY>",
"ETCHV_FILES_ROOT": "<ETCHV_FILES_ROOT>"
}
}
}
}Install Etchv MCP in Codex
$ codex mcp add mcp-server --env 'ETCHV_API_KEY=<YOUR_ETCHV_API_KEY>' --env 'ETCHV_FILES_ROOT=<ETCHV_FILES_ROOT>' -- npx -y @etchv-labs/mcp-serverInstall Etchv MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@etchv-labs/mcp-server"] [mcp_servers.mcp-server.env] ETCHV_API_KEY = "<YOUR_ETCHV_API_KEY>" ETCHV_FILES_ROOT = "<ETCHV_FILES_ROOT>"
Install Etchv MCP in Gemini CLI
$ gemini mcp add -s user -e 'ETCHV_API_KEY=<YOUR_ETCHV_API_KEY>' -e 'ETCHV_FILES_ROOT=<ETCHV_FILES_ROOT>' mcp-server npx -- -y @etchv-labs/mcp-serverInstall Etchv MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@etchv-labs/mcp-server"
],
"env": {
"ETCHV_API_KEY": "<YOUR_ETCHV_API_KEY>",
"ETCHV_FILES_ROOT": "<ETCHV_FILES_ROOT>"
}
}
}
}Etchv MCP tools 14
Detected from the READMEcheck_api_keywatermark_mediadetect_mediacreate_uploadwatermark_batchupdate_assetdelete_assetcreate_linkrevoke_linkredeliver_webhookinput_pathinput_url
| check_api_key | — | |
| watermark_media | — | |
| detect_media | — | |
| create_upload | — | |
| watermark_batch | — | |
| update_asset | — | |
| delete_asset | — | |
| create_link | — | |
| revoke_link | — | |
| redeliver_webhook | — | |
| input_path | — | |
| input_url | — |
Show all 14 toolsShow fewer tools
upload_idasset_id
| upload_id | — | |
| asset_id | — |
Configuration
ETCHV_API_KEYRequiredSecretEtchv API key with the scopes your workflow needs.
ETCHV_FILES_ROOTRequiredAbsolute path of an existing directory for input and output files.
ETCHV_API_BASE_URLOptional HTTPS API origin. Defaults to https://api.etchv.com.
| Name | Description | |
|---|---|---|
| ETCHV_API_KEY | Etchv API key with the scopes your workflow needs. | RequiredSecret |
| ETCHV_FILES_ROOT | Absolute path of an existing directory for input and output files. | Required |
| ETCHV_API_BASE_URL | Optional HTTPS API origin. Defaults to https://api.etchv.com. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubEtchv 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
| Variable | Required | Description |
|---|---|---|
ETCHV_API_KEY |
Yes | Etchv API key. Keep it in your client's secret or env config, never in chat. |
ETCHV_FILES_ROOT |
Yes | Absolute path of an existing directory. All input and output files must be inside it. |
ETCHV_API_BASE_URL |
No | API origin. Defaults to https://api.etchv.com. |
ETCHV_LARGE_FILE_THRESHOLD |
No | Files above this many bytes are uploaded once to a signed URL and sent by ID. Defaults to 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
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:
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:
{
"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
| Tool | What it does | Key scope |
|---|---|---|
check_api_key |
Show organization ID, key ID and scopes; no credits | Any valid key |
watermark_media |
Watermark a file, sync or async; spends credits | watermarks:embed (assets:read for links) |
detect_media |
Detect a watermark, sync or async; uses credits | watermarks:detect |
create_upload |
Create an upload session and return its signed upload URL | watermarks:embed, or watermarks:detect for detect |
get_job, get_job_result |
Read job status; collect a finished result | Matching embed/detect scope |
watermark_batch |
Watermark up to 100 local files in one batch, each with its own data; spends credits | watermarks:embed |
get_batch, download_batch |
Follow a batch; save each result or the batch's zip | watermarks:embed |
list_assets, get_asset, download_asset |
List, inspect, download or link to assets | assets:read |
update_asset |
Rename or replace metadata (version-checked) | assets:write |
delete_asset |
Delete an asset | assets:delete, owner/admin |
create_link |
Share a source asset so each recipient opens their own watermarked copy; copies spend credits | links:write |
list_links, get_link |
List links; read one with each recipient's opens and copy | links:read |
revoke_link |
Stop new opens and downloads of a link | links:write |
delete_link, remove_link_recipient |
Delete a link, or one recipient, with their opens, downloads and copies; can't be undone | links:write, assets:delete, owner/admin |
list_storage_destinations, list_storage_deliveries, get_storage_delivery |
Inspect customer storage | storage:read |
verify_storage_destination, store_asset, retry_storage_delivery |
Test a bucket; deliver or retry a result | storage:write, owner/admin |
list_webhooks, list_webhook_deliveries |
Inspect webhook endpoints and deliveries | webhooks:read |
redeliver_webhook |
Resend an existing event | webhooks: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 insideETCHV_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 theContent-Dispositionheader, else the URL path; passfilenameto set it. Its extension must matchmedia.upload_id: anupl_ID fromcreate_upload. A client that can send files itself callscreate_uploadwithkind(image,document,video, ordetectto check a delivered file),filenameand the exactsizein bytes, PUTs the bytes to the returnedupload.urlwithout an API key, then passesupload_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.filenamecan 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_urlmust 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
- Guide: https://etchv.com/docs/mcp?utm_source=mcp-local&utm_medium=readme&utm_campaign=integrations
- API reference: https://etchv.com/docs?utm_source=mcp-local&utm_medium=readme&utm_campaign=integrations
- Issues: https://github.com/etchv-labs/mcp-server/issues
- Support: hello@etchv.com
Questions or bug reports: open an issue here or email hello@etchv.com.
License
Etchv MCP questions
How do I add Etchv MCP to Claude Code?
Run claude mcp add --env 'ETCHV_API_KEY=<YOUR_ETCHV_API_KEY>' --env 'ETCHV_FILES_ROOT=<ETCHV_FILES_ROOT>' mcp-server -- npx -y @etchv-labs/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Etchv MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Etchv MCP provide?
It exposes 14 tools, including check_api_key, watermark_media, detect_media, create_upload, watermark_batch.
How do I verify my Etchv connection is working?
You can ask the assistant to run the check_api_key tool to confirm the connection and see your organization ID and scopes.
Can I watermark multiple files at once?
Yes, the watermark_batch tool allows you to watermark up to 100 local files in a single batch.
Where are the input and output files stored?
All files must be located within an absolute directory path specified by the ETCHV_FILES_ROOT environment variable.