GroupDocs.Conversion.Mcp

# GroupDocs.Conversion MCP Server

Convert PDF, Word, Excel, PowerPoint, HTML, images, and 70+ document formats from Claude,
Cursor, GitHub Copilot, and any other MCP agent — **locally, your files never leave your machine**.

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

## Install in 60 seconds

Requires the [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) for native runs — or skip straight to [Docker](#docker).

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

```bash
dnx GroupDocs.Conversion.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.Conversion.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-conversion&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.Conversion.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-conversion&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.Conversion.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-conversion&config=eyJjb21tYW5kIjoiZG54IiwiYXJncyI6WyJHcm91cERvY3MuQ29udmVyc2lvbi5NY3AiLCItLXllcyJdLCJlbnYiOnsiR1JPVVBET0NTX01DUF9TVE9SQUdFX1BBVEgiOiIvcGF0aC90by9kb2N1bWVudHMifX0%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 -->

### Claude Desktop

Add to `claude_desktop_config.json`:

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

> To use a license, add `"GROUPDOCS_LICENSE_PATH": "/path/to/GroupDocs.Total.lic"` to `env` —
> omit it to run in [evaluation mode](#licensing).

### Claude Code

```bash
claude mcp add groupdocs-conversion -- dnx GroupDocs.Conversion.Mcp --yes
```

### VS Code / GitHub Copilot

Use the **Install in VS Code** button above, or copy the ready-made snippet from the
[NuGet package page](https://www.nuget.org/packages/GroupDocs.Conversion.Mcp) into `.vscode/mcp.json`,
or take [`install/generated/vscode-mcp.json`](install/generated/vscode-mcp.json) from this repo.

### Visual Studio 2022 (17.14+)

Create `.mcp.json` in your **solution root** with the contents of
[`install/generated/vs2022-mcp.json`](install/generated/vs2022-mcp.json) — same shape as VS Code's.
This is the native path for .NET teams already in Visual Studio.

### Cursor · Windsurf · Cline · Rider

- **Cursor** — use the **Add to Cursor** button above, or paste [`install/generated/claude-desktop.json`](install/generated/claude-desktop.json) into `~/.cursor/mcp.json`.
- **Windsurf** — paste [`install/generated/windsurf.json`](install/generated/windsurf.json) into `~/.codeium/windsurf/mcp_config.json`.
- **Cline** — paste [`install/generated/cline.json`](install/generated/cline.json) into Cline's MCP settings.
- **JetBrains Rider** — follow [`install/generated/rider.md`](install/generated/rider.md).

### Docker

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

Images are published to both GHCR (`ghcr.io/groupdocs-conversion/conversion-net-mcp`) and
Docker Hub (`groupdocs/conversion-net-mcp`) for `linux/amd64` + `linux/arm64`, tagged
`latest` plus an immutable version tag matching each NuGet release (e.g. `:26.7.1`).

### Global dotnet tool

```bash
dotnet tool install -g GroupDocs.Conversion.Mcp
groupdocs-conversion-mcp
```

> **Version pinning:** in any snippet above, replace `"GroupDocs.Conversion.Mcp"` with
> `"GroupDocs.Conversion.Mcp@26.7.1"` to lock to a specific release. Pinning is recommended
> for shared / committed configs to avoid surprise upgrades.

## Available MCP Tools

| Tool | Description |
|---|---|
| `Convert` | Converts a document to a different format (PDF, DOCX, XLSX, PPTX, HTML, PNG, JPG, and 70+ more) and saves the result to storage |
| `GetSupportedFormats` | Lists every target format the source document can be converted to, with primary/secondary indicators |
| `GetDocumentInfo` | Returns file type, page count, and basic properties (author, title, dates, password-protected) for a source document |

## Licensing

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

- Converted output carries an evaluation watermark, and tool responses include an
  evaluation-mode notice.
- A single server process can open at most **15 documents**; further calls fail with
  *"Could not open more than 15 document files in evaluation mode"* until the server restarts.

To lift the limits, point `GROUPDOCS_LICENSE_PATH` at your `GroupDocs.Total.lic` (see the
commented example in each install snippet above):

- [Get a free 30-day temporary license](https://purchase.groupdocs.com/temporary-license/)
- [Purchase a license](https://purchase.groupdocs.com/pricing/conversion/net) · [Product page](https://products.groupdocs.com/conversion/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) |

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

## 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.Conversion.Mcp.Tests**](https://github.com/groupdocs-conversion/GroupDocs.Conversion.Mcp.Tests):

- [Install from NuGet](https://github.com/groupdocs-conversion/GroupDocs.Conversion.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-conversion/GroupDocs.Conversion.Mcp.Tests/blob/master/how-to/02-run-via-docker.md)
- [Verify on the MCP registry](https://github.com/groupdocs-conversion/GroupDocs.Conversion.Mcp.Tests/blob/master/how-to/03-verify-mcp-registry.md)
- [Use with Claude Desktop](https://github.com/groupdocs-conversion/GroupDocs.Conversion.Mcp.Tests/blob/master/how-to/04-use-with-claude-desktop.md)
- [Use with VS Code / GitHub Copilot](https://github.com/groupdocs-conversion/GroupDocs.Conversion.Mcp.Tests/blob/master/how-to/05-use-with-vscode-copilot.md)
- [Run the integration tests](https://github.com/groupdocs-conversion/GroupDocs.Con