GroupDocs.Comparison.Mcp

# GroupDocs.Comparison MCP Server

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

[![NuGet](https://img.shields.io/nuget/v/GroupDocs.Comparison.Mcp?label=NuGet)](https://www.nuget.org/packages/GroupDocs.Comparison.Mcp)
[![NuGet downloads](https://img.shields.io/nuget/dt/GroupDocs.Comparison.Mcp?label=downloads)](https://www.nuget.org/packages/GroupDocs.Comparison.Mcp)
[![Docker pulls](https://img.shields.io/docker/pulls/groupdocs/comparison-net-mcp?label=docker%20pulls)](https://hub.docker.com/r/groupdocs/comparison-net-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6f42c1)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.groupdocs-comparison/groupdocs-comparison-mcp)
[![Integration tests](https://github.com/groupdocs-comparison/GroupDocs.Comparison.Mcp.Tests/actions/workflows/integration.yml/badge.svg)](https://github.com/groupdocs-comparison/GroupDocs.Comparison.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

<!-- 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-comparison&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Comparison.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) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5)](https://insiders.vscode.dev/redirect/mcp/install?name=groupdocs-comparison&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Comparison.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) [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP-111111)](https://cursor.com/en/install-mcp?name=groupdocs-comparison&config=eyJjb21tYW5kIjoiZG54IiwiYXJncyI6WyJHcm91cERvY3MuQ29tcGFyaXNvbi5NY3AiLCItLXllcyJdLCJlbnYiOnsiR1JPVVBET0NTX01DUF9TVE9SQUdFX1BBVEgiOiIvcGF0aC90by9kb2N1bWVudHMiLCJHUk9VUERPQ1NfTUNQX09VVFBVVF9QQVRIIjoiL3BhdGgvdG8vZG9jdW1lbnRzIiwiR1JPVVBET0NTX0xJQ0VOU0VfUEFUSCI6IiJ9fQ%3D%3D) [![Codex CLI setup](https://img.shields.io/badge/Codex_CLI-Setup-e5541b)](install/generated/codex.md) [![Windsurf setup](https://img.shields.io/badge/Windsurf-Setup-0e8a7d)](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.Comparison.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.Comparison.Mcp@26.9.1 --yes
```

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

```bash
dotnet tool install -g GroupDocs.Comparison.Mcp
groupdocs-comparison-mcp
```

**Or run via Docker:**

```bash
docker run --rm -i \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-comparison/comparison-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 |
|---|---|
| `Compare` | Compares two documents (source vs target) and produces a marked-up result **file**, plus a change-count summary and a structured JSON list of the changes (type, page, the changed fragment, surrounding source/target text, table cell, style changes). Use when the user wants the rendered diff document. Supports PDF, Word, Excel, PowerPoint, ODT, RTF, TXT, HTML, and 30+ more formats; optional `sourcePassword` / `targetPassword` cover protected documents. |
| `AnalyzeChanges` | Returns the differences between two documents as **structured data only** — the same JSON change list as `Compare`, but **without** rendering or saving a result file. Cheaper than `Compare`; use when the user wants to summarize, explain, or reason about *what* changed rather than obtain the marked-up file. Optional `sourcePassword` / `targetPassword`. |
| `GetDocumentInfo` | Inspects a single source document and returns file type, page count, file size, and per-page dimensions as JSON — without performing a comparison. Useful as a pre-flight check before deciding whether to compare or which formats to expect. Optional `password` for protected documents. |

## Example prompts for AI agents

Once the server is wired up to your MCP client (Claude Desktop, Cursor, VS Code Copilot, …), try:

```
Compare old.pdf and new.pdf and save the marked-up result.

Diff contract-v1.docx against contract-v2.docx and tell me the change count.

What changed between proposal-v1.docx and proposal-v2.docx? Summarize the edits.

Did the prices change between budget-q1.xlsx and budget-q2.xlsx? Which cells?

How many pages does report.pdf have? Who's the author?

Inspect /docs/legal-brief.pdf — what's the file type and page count?
```

The client picks `Compare` when the user wants the rendered diff **file**,
`AnalyzeChanges` when they only want to know **what** changed (summary /
analysis, no file), and `GetDocumentInfo` for inspection-only questions.

## Licensing

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

- Comparison output may carry evaluation watermarks / notices.
- 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-comparison/comparison-net-mcp:latest
```

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

## 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