GroupDocs.Watermark.Mcp

# GroupDocs.Watermark MCP Server

MCP server that exposes [GroupDocs.Watermark](https://products.groupdocs.com/watermark) as AI-callable tools
for Claude, Cursor, GitHub Copilot, and other MCP agents.

[![NuGet](https://img.shields.io/nuget/v/GroupDocs.Watermark.Mcp?label=NuGet)](https://www.nuget.org/packages/GroupDocs.Watermark.Mcp)
[![NuGet downloads](https://img.shields.io/nuget/dt/GroupDocs.Watermark.Mcp?label=downloads)](https://www.nuget.org/packages/GroupDocs.Watermark.Mcp)
[![Docker pulls](https://img.shields.io/docker/pulls/groupdocs/watermark-net-mcp?label=docker%20pulls)](https://hub.docker.com/r/groupdocs/watermark-net-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6f42c1)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.groupdocs-watermark/groupdocs-watermark-mcp)
[![Integration tests](https://github.com/groupdocs-watermark/GroupDocs.Watermark.Mcp.Tests/actions/workflows/integration.yml/badge.svg)](https://github.com/groupdocs-watermark/GroupDocs.Watermark.Mcp.Tests/actions/workflows/integration.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<!-- TODO(manual): record 30s demo per improvement-plan M1 -->
<!-- ![Demo](assets/demo.gif) -->

## Installation

Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0).

**Run directly with `dnx` (recommended — no install step):**

```bash
dnx GroupDocs.Watermark.Mcp --yes
```

Pulls the latest stable release on every invocation. To pin to a specific
version (recommended for shared configs and CI), append `@<version>`:

```bash
dnx GroupDocs.Watermark.Mcp@26.7.1 --yes
```

<!-- install-buttons:start - generated by install/generate-install-links.ps1; do not edit by hand -->
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF)](https://vscode.dev/redirect/mcp/install?name=groupdocs-watermark&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22storage_path%22%2C%22description%22%3A%22Base%20folder%20for%20input%20and%20output%20files%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22license_path%22%2C%22description%22%3A%22Path%20to%20GroupDocs%20license%20file%20%28optional%20-%20evaluation%20mode%20if%20empty%29%22%7D%5D&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Watermark.Mcp%22%2C%22--yes%22%5D%2C%22env%22%3A%7B%22GROUPDOCS_MCP_STORAGE_PATH%22%3A%22%24%7Binput%3Astorage_path%7D%22%2C%22GROUPDOCS_LICENSE_PATH%22%3A%22%24%7Binput%3Alicense_path%7D%22%7D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5)](https://insiders.vscode.dev/redirect/mcp/install?name=groupdocs-watermark&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22storage_path%22%2C%22description%22%3A%22Base%20folder%20for%20input%20and%20output%20files%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22license_path%22%2C%22description%22%3A%22Path%20to%20GroupDocs%20license%20file%20%28optional%20-%20evaluation%20mode%20if%20empty%29%22%7D%5D&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Watermark.Mcp%22%2C%22--yes%22%5D%2C%22env%22%3A%7B%22GROUPDOCS_MCP_STORAGE_PATH%22%3A%22%24%7Binput%3Astorage_path%7D%22%2C%22GROUPDOCS_LICENSE_PATH%22%3A%22%24%7Binput%3Alicense_path%7D%22%7D%7D&quality=insiders) [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP-111111)](https://cursor.com/en/install-mcp?name=groupdocs-watermark&config=eyJjb21tYW5kIjoiZG54IiwiYXJncyI6WyJHcm91cERvY3MuV2F0ZXJtYXJrLk1jcCIsIi0teWVzIl0sImVudiI6eyJHUk9VUERPQ1NfTUNQX1NUT1JBR0VfUEFUSCI6Ii9wYXRoL3RvL2RvY3VtZW50cyJ9fQ%3D%3D)

> One-click buttons prompt for your documents folder (and optional license). Cursor's
> deeplink installs with a placeholder storage path - edit it after install.
<!-- install-buttons:end -->

> **More clients** — ready-made configs for Claude Code, Visual Studio 2022 (`.mcp.json`),
> Cursor, Windsurf, Cline, and JetBrains Rider live in [`install/generated/`](install/generated/).

**Or install as a global dotnet tool:**

```bash
dotnet tool install -g GroupDocs.Watermark.Mcp
groupdocs-watermark-mcp
```

**Or run via Docker:**

```bash
docker run --rm -i \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-watermark/watermark-net-mcp:latest
```

## Native prerequisites

The underlying GroupDocs engine uses `System.Drawing` (GDI+) for some
operations. When you run the server **natively** (via `dnx` or the global
dotnet tool) on Linux or macOS, install the native `libgdiplus` library first:

| Platform | Setup |
|---|---|
| Windows | Nothing — GDI+ is built into the OS. |
| Linux | `sudo apt-get install -y libgdiplus libfontconfig1 ttf-mscorefonts-installer` |
| macOS | `brew install mono-libgdiplus` |
| Docker | Nothing — the image already bundles `libgdiplus`. |

Skipping this on Linux/macOS surfaces as `DllNotFoundException: libgdiplus` in
the tool response. The simplest zero-setup option on Linux/macOS is the
**Docker image**.

## Available MCP Tools

| Tool | Description |
|---|---|
| `AddWatermark` | Adds a text watermark (Arial, configurable size + rotation) to a document and saves the watermarked file to storage |
| `AddImageWatermark` | Adds an image watermark (logo, signature scan, stamp) to a document and saves the watermarked file. Configurable opacity + rotation |
| `SearchWatermarks` | Finds existing watermarks (text + image) in a document and returns their details (type, text, page, position, size, rotation) as JSON |
| `RemoveWatermarks` | Removes existing watermarks from a document and saves the cleaned copy. Optional text filter to remove only matching watermarks |
| `GetDocumentInfo` | Returns the file type, page count, and per-page dimensions of a document as JSON — without modifying it |

All tools support PDF, DOCX, XLSX, PPTX, PNG, JPG, VSDX, and 50+ more document and image formats.

## Example prompts for AI agents

Copy any of these into Claude Desktop, Cursor, or GitHub Copilot Chat after the
server is connected. The AI agent will pick the right tool and arguments
automatically — file names are resolved against `GROUPDOCS_MCP_STORAGE_PATH`.

1. **Add a DRAFT text watermark**: *"Add a watermark with the text 'DRAFT' to report.pdf."*
2. **Stamp a logo image**: *"Use company-logo.png as an image watermark on every page of contract.docx, opacity 30%."*
3. **Inspect existing watermarks**: *"What watermarks does invoice.pdf contain?"*
4. **Strip old watermarks**: *"Remove all watermarks from final-draft.docx so I can ship it."*
5. **Inspect document structure**: *"How many pages does presentation.pptx have, and what are their dimensions?"*

## Licensing

**The MCP server itself is MIT; the underlying GroupDocs.Watermark engine requires a license
for production use.** Without one the server runs in **evaluation mode**:

- The engine adds an extra evaluation watermark to processed output.
- A single server process can load at most **10 documents**; further calls fail until the server restarts.

To lift the limits, point `GROUPDOCS_LICENSE_PATH` at your `GroupDocs.Total.lic`:

- [Get a free 30-day temporary license](https://purchase.groupdocs.com/temporary-license/)
- [Purchase a license](https://purchase.groupdocs.com/pricing/watermark/net) | [Product page](https://products.groupdocs.com/watermark/net/)

## Configuration

| Variable | Description | Default |
|---|---|---|
| `GROUPDOCS_MCP_STORAGE_PATH` | Base folder for input and output files | current directory |
| `GROUPDOCS_MCP_OUTPUT_PATH` | *(Optional)* separate folder for output files | `GROUPDOCS_MCP_STORAGE_PATH` |
| `GROUPDOCS_LICENSE_PATH` | Path to GroupDocs license file. In evaluation mode, output documents may include an additional evaluation watermark alongside the user-requested one | (evaluation mode) |

## Usage with Claude Desktop

```json
{
  "mcpServers": {
    "groupdocs-watermark": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Watermark.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents"
      }
    }
  }
}
```

> To pin to a specific version, replace `"GroupDocs.Watermark.Mcp"` with
> `"GroupDocs.Watermark.Mcp@26.7.1"` in `args`. Pinning is recommended for
> shared / committed configs to avoid surprise upgrades.

## Usage with VS Code / GitHub Copilot

NuGet.org generates a ready-to-use `mcp.json` snippet on the [package page](https://www.nuget.org/packages/GroupDocs.Watermark.Mcp).
Copy it directly into your `.vscode/mcp.json`.

Alternatively, add manually to `.vscode/mcp.json`:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Base folder for input and output files.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-watermark": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Watermark.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "${input:storage_path}"
      }
    }
  }
}
```

> Same pinning rule as above — swap `"GroupDocs.Watermark.Mcp"` for
> `"GroupDocs.Watermark.Mcp@26.7.1"` to lock to a specific release.

## Usage with Docker Compose

```bash
cd docker
docker compose up
```

Edit `docker/docker-compose.yml` to point volumes at your local documents folder.

## Documentation & guides

Step-by-step deployment guides and a published-package integration test suite
live in the companion repo
[**GroupDocs.Watermark.Mcp.Tests**](https://github.com/groupdocs-watermark/GroupDocs.Watermark.Mcp.Tests):

- [Install from NuGet](https://github.com/groupdocs-watermark/GroupDocs.Watermark.Mcp.Tests/blob/master/how-to/01-install-from-nuget.md) — `dnx`, global tool, pinned vs always-latest
- [Run via Docker](https://github.com/groupdocs-watermark/GroupDocs.Watermark.Mcp.Tests/blob/master/how-to/02-run-via-docker.md)
- [Verify on the MCP registry](https://github.com/groupdocs-watermark/GroupDocs.Watermark.Mcp.Tests/blob/master/how-to/03-verify-mcp-registry.md)
- [Use with Claude Deskto