io.github.groupdocs-annotation/groupdocs-annotation-mcp
MCP server for GroupDocs.Annotation — add, list, update, remove document annotations via AI agents.
Open source Open in the app JSON README (API)
About
MCP server for GroupDocs.Annotation — add, list, update, remove document annotations via AI agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- groupdocs-annotation
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 26.9.0
- Last push
- 2026-09-04T17:21:15Z
- Repository state
- ativo
- Language
- C#
- License
- MIT
- Added
- 2026-08-29 03:02:54
- Updated
- 2026-09-04 18:00:35
- Origin id
io.github.groupdocs-annotation/groupdocs-annotation-mcp
README
# GroupDocs.Annotation MCP Server
MCP server that exposes [GroupDocs.Annotation](https://products.groupdocs.com/annotation) as AI-callable tools
for Claude, Cursor, GitHub Copilot, and other MCP agents.
[](https://www.nuget.org/packages/GroupDocs.Annotation.Mcp)
[](https://www.nuget.org/packages/GroupDocs.Annotation.Mcp)
[](https://hub.docker.com/r/groupdocs/annotation-net-mcp)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.groupdocs-annotation/groupdocs-annotation-mcp)
[](https://github.com/groupdocs-annotation/GroupDocs.Annotation.Mcp.Tests/actions/workflows/integration.yml)
[](LICENSE)
<!-- TODO(manual): record 30s demo per improvement-plan M1 -->
<!--  -->
## Installation
<!-- install-buttons:start - generated by install/generate-install-links.ps1; do not edit by hand -->
[](https://vscode.dev/redirect/mcp/install?name=groupdocs-annotation&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Annotation.Mcp%22%2C%22--yes%22%5D%2C%22env%22%3A%7B%22GROUPDOCS_MCP_STORAGE_PATH%22%3A%22%2Fpath%2Fto%2Fdocuments%22%2C%22GROUPDOCS_MCP_OUTPUT_PATH%22%3A%22%2Fpath%2Fto%2Fdocuments%22%2C%22GROUPDOCS_LICENSE_PATH%22%3A%22%22%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=groupdocs-annotation&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Annotation.Mcp%22%2C%22--yes%22%5D%2C%22env%22%3A%7B%22GROUPDOCS_MCP_STORAGE_PATH%22%3A%22%2Fpath%2Fto%2Fdocuments%22%2C%22GROUPDOCS_MCP_OUTPUT_PATH%22%3A%22%2Fpath%2Fto%2Fdocuments%22%2C%22GROUPDOCS_LICENSE_PATH%22%3A%22%22%7D%7D&quality=insiders) [](https://cursor.com/en/install-mcp?name=groupdocs-annotation&config=eyJjb21tYW5kIjoiZG54IiwiYXJncyI6WyJHcm91cERvY3MuQW5ub3RhdGlvbi5NY3AiLCItLXllcyJdLCJlbnYiOnsiR1JPVVBET0NTX01DUF9TVE9SQUdFX1BBVEgiOiIvcGF0aC90by9kb2N1bWVudHMiLCJHUk9VUERPQ1NfTUNQX09VVFBVVF9QQVRIIjoiL3BhdGgvdG8vZG9jdW1lbnRzIiwiR1JPVVBET0NTX0xJQ0VOU0VfUEFUSCI6IiJ9fQ%3D%3D) [](install/generated/codex.md) [](install/generated/windsurf.md)
> 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/`](install/generated/).
<!-- install-buttons:end -->
Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0).
**Run directly with `dnx` (recommended — no install step):**
```bash
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>`:
```bash
dnx GroupDocs.Annotation.Mcp@26.9.0 --yes
```
**Or install as a global dotnet tool:**
```bash
dotnet tool install -g GroupDocs.Annotation.Mcp
groupdocs-annotation-mcp
```
**Or run via Docker:**
```bash
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:
```bash
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](https://purchase.groupdocs.com/temporary-license/)
- [Purchase a license](https://purchase.groupdocs.com/pricing/annotation/net) | [Product page](https://products.groupdocs.com/annotation/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 | (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](#licensing) | (unset) |
## Usage with Claude Desktop
```json
{
"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](https://www.nuget.org/packages/GroupDocs.Annotation.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-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
```bash
cd docker
docker compose up
```
Edit `docker/docker-compose.yml` to point volumes at your local documents folder.
## License
MIT — see [LICENSE](LICENSE)
<!-- mcp-name: io.github.groupdocs-annotation/groupdocs-annotation-mcp -->