valepara-mcp

MCP Server Documentation

Add text watermarks to images and PDFs programmatically via AI agents. Runs locally — files never leave your machine.

Getting Started

Install the MCP server and configure your AI assistant to use it.

Quick install

npx valepara-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "valepara": {
      "command": "npx",
      "args": ["-y", "valepara-mcp"]
    }
  }
}

Claude Code

claude mcp add valepara-mcp -- npx -y valepara-mcp

Tools Reference

watermark-image

Add a repeating text watermark to an image file (JPG, PNG, WebP). Returns the watermarked file path and a preview image.

Parameter	Type	Default	Description
imagePath	string	required	Absolute path to the source image
outputPath	string	auto	Output path. Defaults to {name}-watermarked.{ext}
text	string	"ONLY VALID FOR"	Watermark text to repeat
opacity	number	0.4	Opacity (0-1)
fontSize	number	28	Font size in pixels
rotation	number	-30	Rotation angle (-90 to 90 degrees)
color	string	"#ff0000"	Hex color
spacing	number	100	Gap between repetitions in px
wavy	boolean	false	Apply wavy text effect
wavyAmplitude	number	8	Wave height in px
wavyFrequency	number	0.05	Wave oscillation frequency

Example

Use watermark-image on /Users/me/id-card.jpg
  with text "COPY - NOT VALID"
  opacity 0.5
  color "#ff0000"
  fontSize 32

watermark-pdf

Add a repeating text watermark to all pages of a PDF file. Same parameters as watermark-image but with pdfPath instead of imagePath.

Example

Use watermark-pdf on /Users/me/contract.pdf
  with text "DRAFT - CONFIDENTIAL"
  color "#888888"
  fontSize 48
  opacity 0.3

detect-document

Detect the document boundary in a photo using Canny edge detection. Returns 4 corner points (TL, TR, BR, BL) or null if no document is found.

Parameter	Type	Default	Description
imagePath	string	required	Path to a photo containing a document

Response

{
  "detected": true,
  "corners": [
    { "x": 120, "y": 85 },
    { "x": 890, "y": 90 },
    { "x": 885, "y": 620 },
    { "x": 115, "y": 615 }
  ],
  "imageWidth": 1024,
  "imageHeight": 768
}

Common Use Cases

Watermark a batch of images

Ask your AI assistant to watermark multiple files at once:

Watermark all JPG files in /Users/me/documents/
with text "PERSONAL COPY" opacity 0.3 color "#0000ff"

Detect then watermark

First detect the document area, then apply watermark only to that region:

1. detect-document on /Users/me/photo-of-passport.jpg
2. If detected, watermark-image with the bounds
   text "VALID FOR RENTAL ONLY"
   rotation -30

Prepare documents for sharing

Watermark sensitive documents before sending:

Watermark /Users/me/tax-return.pdf
with text "SHARED WITH: Acme Corp - March 2026"
opacity 0.2 fontSize 16 color "#999999"

Privacy

100% local processing

The MCP server runs entirely on your machine. No files are uploaded to any external service. Watermarking happens in-process using Sharp (images) and pdf-lib (PDFs). Your documents never leave your computer.

← Home Try the tool →