io.github.groupdocs-annotation/groupdocs-annotation-mcp

GroupDocs.Annotation MCP Server

MCP server that exposes GroupDocs.Annotation as AI-callable tools for Claude, Cursor, GitHub Copilot, and other MCP agents.

Installation

One-click installs pre-fill every supported setting: edit the placeholder documents folder after install (output defaults to the same folder); an empty GROUPDOCS_LICENSE_PATH runs in evaluation mode - point it at your license to lift limits.

More clients - ready-made configs for Claude Code, Codex CLI, Visual Studio 2022, Cursor, Windsurf, Cline, and JetBrains Rider live in install/generated/.

Requires .NET 10 SDK.

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

dnx GroupDocs.Annotation.Mcp --yes

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

dnx GroupDocs.Annotation.Mcp@26.9.0 --yes

Or install as a global dotnet tool:

dotnet tool install -g GroupDocs.Annotation.Mcp
groupdocs-annotation-mcp

Or run via Docker:

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

Native prerequisites

The underlying GroupDocs engine rasterises annotated pages and previews via System.Drawing (GDI+). When you run the server natively (via dnx or the global dotnet tool) on Linux or macOS, install the native libgdiplus library and a fonts package 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, libfontconfig1, and ttf-mscorefonts-installer.

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
AddAnnotation	Add a textfield / area / point / arrow / highlight / underline / strikeout annotation; saves the annotated file as <name>_annotated.<ext>
GetAnnotations	List all annotations in a document as JSON (id, type, message, page, box, user, replies)
UpdateAnnotation	Modify an existing annotation's message and/or bounding box by id
RemoveAnnotations	Remove annotations by id list, or all if none specified
AddReply	Add a reply / comment thread to an existing annotation
RemoveReplies	Remove replies by reply-id list, by user name, or all
ImportAnnotations	Import annotations from an XML file or another annotated document into a target file
ExportAnnotations	Extract annotations from a document and save them as XML (re-importable via ImportAnnotations)
GetDocumentInfo	Return file type, page count, size, and per-page dimensions as JSON (no modification)
GeneratePagesPreview	Render up to 5 document pages as inline PNG images so AI clients display them directly

Example prompts

• "Annotate contract.pdf — add a highlight on page 2 around the indemnity clause and an arrow with the comment 'Needs legal review'"
• "List every annotation in design-review.docx and group them by author"
• "Reply to annotation 7 in spec.pdf with 'Implemented in PR #42' under the user 'alice'"
• "Export the annotations from old.pdf to XML, then re-import them into new.pdf"
• "Preview page 1 and page 5 of report.pdf with annotations baked in"

Licensing

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

• Annotated output may carry evaluation watermarks.
• A single server process can open at most 15 documents; further calls fail with an evaluation-cap error until the server restarts.

There are two ways to license the server.

License file — point GROUPDOCS_LICENSE_PATH at your GroupDocs.Total.lic. Works offline.

Metered (pay-per-use) — set both GROUPDOCS_METERED_PUBLIC_KEY and GROUPDOCS_METERED_PRIVATE_KEY. You are billed for what you actually process, which suits AI agents well because their usage is bursty and hard to predict up front. If both a metered key pair and a license file are configured, metered wins and the file is ignored.

Metered mode needs outbound connectivity. Usage is reported to GroupDocs servers, so air-gapped or firewalled deployments must allow that egress — or use a license file instead.

Call the get_license_status tool at any time to see which mode is active, and — under metered — the consumed quantity and remaining credit.

Keeping the private key out of your config

The metered private key is a secret. MCP client configs are plain files on disk, and a project-scoped .mcp.json is committed by convention, so prefer, in order:

1. Set the variables in your OS environment and leave them out of the config entirely. An stdio MCP server inherits its client's environment, so this works in every client. On macOS note that an app launched from Finder does not inherit shell exports — use launchctl setenv, or launch the client from a terminal.
2. Reference them indirectly if your client supports it (Claude Code expands ${VAR}; VS Code uses ${env:VAR} and ${input:...}).
3. A literal value in a user-scoped config (for example ~/.claude.json) is acceptable for a single developer.
4. Never commit a literal key in a project-scoped .mcp.json.

For Docker, forward the values without writing them into any file:

docker run --rm -i \
  -e GROUPDOCS_METERED_PUBLIC_KEY -e GROUPDOCS_METERED_PRIVATE_KEY \
  -v /path/to/documents:/data \
  ghcr.io/groupdocs-annotation/annotation-net-mcp:latest

To lift the limits with a license file:

• Get a free 30-day temporary license
• Purchase a license | Product page

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	(evaluation mode)
GROUPDOCS_METERED_PUBLIC_KEY	Metered public key. Requires the private key too; takes precedence over the license file	(unset)
GROUPDOCS_METERED_PRIVATE_KEY	Metered private key. Secret - see Licensing	(unset)

Usage with Claude Desktop

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

To pin to a specific version, replace "GroupDocs.Annotation.Mcp" with "GroupDocs.Annotation.Mcp@26.9.0" 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. Copy it directly into your .vscode/mcp.json.

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

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

Same pinning rule as above — swap "GroupDocs.Annotation.Mcp" for "GroupDocs.Annotation.Mcp@26.9.0" to lock to a specific release.

Usage with Docker Compose

cd docker
docker compose up

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

License

MIT — see LICENSE