GroupDocs.Editor MCP Server
OfficialREADME.md
# GroupDocs.Editor MCP Server
Let Claude, Cursor, GitHub Copilot and any other MCP agent **edit Word, Excel, PowerPoint, PDF and
text documents without wrecking their formatting** — replace text in place, round-trip a document
(or one worksheet, slide or PDF page range) through editable HTML, and fill Word form fields.
**Locally: your files never leave your machine.**
[](https://www.nuget.org/packages/GroupDocs.Editor.Mcp)
[](https://www.nuget.org/packages/GroupDocs.Editor.Mcp)
[](https://hub.docker.com/r/groupdocs/editor-net-mcp)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.groupdocs-editor/groupdocs-editor-mcp)
[](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests/actions/workflows/integration.yml)
[](LICENSE)
## Install in 60 seconds
<!-- install-buttons:start - generated by install/generate-install-links.ps1; do not edit by hand -->
[](https://vscode.dev/redirect/mcp/install?name=groupdocs-editor&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Editor.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-editor&config=%7B%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22GroupDocs.Editor.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-editor&config=eyJjb21tYW5kIjoiZG54IiwiYXJncyI6WyJHcm91cERvY3MuRWRpdG9yLk1jcCIsIi0teWVzIl0sImVudiI6eyJHUk9VUERPQ1NfTUNQX1NUT1JBR0VfUEFUSCI6Ii9wYXRoL3RvL2RvY3VtZW50cyIsIkdST1VQRE9DU19NQ1BfT1VUUFVUX1BBVEgiOiIvcGF0aC90by9kb2N1bWVudHMiLCJHUk9VUERPQ1NfTElDRU5TRV9QQVRIIjoiIn19) [](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 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.Editor.Mcp --yes
```
Pulls the latest stable release on every invocation. To pin a version (recommended for shared
configs and CI), append `@<version>`:
```bash
dnx GroupDocs.Editor.Mcp@26.10.0 --yes
```
The server reads and writes documents in `GROUPDOCS_MCP_STORAGE_PATH` (default: the current
directory). Edited copies are saved next to the originals and never overwrite an existing file.
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"groupdocs-editor": {
"type": "stdio",
"command": "dnx",
"args": ["GroupDocs.Editor.Mcp", "--yes"],
"env": {
"GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents"
}
}
}
}
```
> To use a license, add `"GROUPDOCS_LICENSE_PATH": "/path/to/GroupDocs.Editor.lic"` to `env` —
> omit it to run in [evaluation mode](#evaluation-mode).
### Claude Code
```bash
claude mcp add groupdocs-editor -- dnx GroupDocs.Editor.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.Editor.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).
### Cursor · Windsurf · Cline · Rider · Codex
- **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** — follow [`install/generated/windsurf.md`](install/generated/windsurf.md).
- **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).
- **Codex CLI** — `codex mcp add groupdocs-editor -- dnx GroupDocs.Editor.Mcp --yes`, details in [`install/generated/codex.md`](install/generated/codex.md).
### Docker
```bash
docker run --rm -i \
-v "$(pwd)/documents:/data" \
ghcr.io/groupdocs-editor/editor-net-mcp:latest
```
Images are published to GHCR (`ghcr.io/groupdocs-editor/editor-net-mcp`) and Docker Hub
(`groupdocs/editor-net-mcp`) for `linux/amd64` + `linux/arm64`, tagged `latest` plus an immutable
version tag matching each NuGet release (e.g. `:26.10.0`). The image needs no native setup.
#### Docker on Linux: run the container as your user
The image runs as a non-root user (uid 1654), and a bind mount keeps its host owner — so on a
**Linux host** every edited file the server writes into `/data` fails with `Permission denied`
unless the container runs as you:
```bash
docker run --rm -i --user "$(id -u):$(id -g)" \
-v "$(pwd)/documents:/data" \
ghcr.io/groupdocs-editor/editor-net-mcp:latest
```
JSON client configs run no shell, so put the numbers in: `"args": ["run", "--rm", "-i", "--user",
"1000:1000", …]`. Docker Desktop on Windows and macOS does not need this.
### Global dotnet tool
```bash
dotnet tool install -g GroupDocs.Editor.Mcp
groupdocs-editor-mcp
```
## Available MCP Tools
| Tool | What it does |
|---|---|
| `get_document_info` | Format family, format, number of pages / worksheets / slides, size, encryption, and the formats it can be saved to (JSON) |
| `extract_html` | Turns a document — or one worksheet, one slide, or a PDF page range — into editable HTML saved to storage, plus a plain-text preview. Self-contained by default; `embedResources=false` writes a `<name>_resources` folder |
| `save_from_html` | Saves edited HTML back as DOCX, DOC, RTF, ODT, XLSX, XLS, ODS, CSV, PPTX, PPT, ODP, PDF, XPS, TXT, Markdown, MHTML, EPUB, MOBI, AZW3, EML or MSG. With `sourceFile` + `worksheet`/`slide` it splices one edited part back into the original and keeps every other part |
| `replace_text` | Find and replace that keeps formatting — literal, case-insensitive, whole-word or regex; one worksheet or slide at a time; optional output format. Reports how many occurrences changed; **writes nothing when nothing matched** |
| `get_supported_formats` | The formats GroupDocs.Editor can open and save, per family, or the save targets of one file (JSON) |
| `get_form_fields` | Lists a Word document's form fields — text boxes, check boxes, drop-downs, number and date fields — with type and value (JSON) |
| `fill_form_fields` | Fills Word form fields and saves a filled copy; unknown names and values that do not fit are reported, never ignored |
| `get_license_status` | Licensing mode, metered consumption and engine version (shipped by GroupDocs.Mcp.Core) |
Worksheet, slide and page numbers are **1-based**. Every failure sets `isError` and starts with the
tool's prefix, e.g. `HTML extraction failed for 'report.docx': …`, so a client needs one check.
## Example prompts for AI agents
```
Replace "ACME Corp" with "Globex" in contract.docx and keep the formatting.
Give me the second worksheet of budget.xlsx as HTML so I can edit it.
Save edited.html back as a Word document, and also as a PDF.
Fill the form fields in application.docx: name = Jane Doe, agree = yes.
Which formats can GroupDocs.Editor open and save?
```
## Evaluation mode
**The MCP server itself is MIT; the GroupDocs.Editor engine requires a license for production use.**
Without one every tool still works, with these limits (measured on GroupDocs.Editor 26.6.1):
- Edited output starts with an evaluation banner ("Created with evaluation version of GroupDocs.Editor …").
- A saved workbook gains an extra worksheet.
- Only the first 2 pages of a PDF, the first 2 (visible) worksheets of a workbook and the first 2 slides of a
presentation can be edited. The engine would silently return part 2 for a higher number; the server refuses
the request instead and says why. Saving an edited part back into worksheet or slide 3+ is not limited.
Responses of the editing tools then start with one `Evaluation mode:` line. Call
**`get_license_status`** to see which mode is active.
## Licensing
There are two ways to license the server.
**License file** — point `GROUPDOCS_LICENSE_PATH` at your GroupDocs.Editor (or GroupDocs.Total)
license file. Works offline.
**Metered (pay-per-use)** — set both `GROUPDOCS_METERED_PUBLIC_KEY` and
`GROUPDOCS_METERED_PRIVATE_KEY`. You pay for what you process, which suits agent workloads. 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.
### Keeping the private key out of your config
The metered private key is a secret. MCP client configs are plain files, 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. On macOS 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-editor/editor-net-mcp:latest
```
- [Get a free 30-day temporary license](https://purchase.groupdocs.com/temporary-license/)
- [Purchase a license](https://purchase.groupdocs.com/pricing/editor/net) · [Product page](https://products.groupdocs.com/editor/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 a 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) |
## Native prerequisites
GroupDocs.Editor draws through Aspose.Drawing (managed) and SkiaSharp, whose native libraries ship
inside the package — **no `libgdiplus` is needed** on any platform. Saving edited content to PDF or
XPS lays text out, so Linux needs real fonts:
| Platform | Setup |
|---|---|
| Windows | Nothing. |
| Linux | `sudo apt-get install -y libfontconfig1 ttf-mscorefonts-installer` (only for PDF/XPS output) |
| macOS | Nothing. |
| Docker | Nothing — the image bundles the fonts. |
## Limits
- **`replace_text` matches within one formatting run.** A phrase split across differently formatted
text (half bold, half not) is not matched; use `extract_html` and `save_from_html` for such edits.
- **PDF editing is a conversion.** A PDF is turned into flowing HTML and back, so complex layouts do
not round-trip perfectly. Save the edited result as DOCX if fidelity matters.
- **PPTX and email outputs need an original.** `save_from_html` creates DOCX, XLSX, PDF, TXT,
Markdown and EPUB from HTML alone; for PPTX and EML/MSG pass the original as `sourceFile`.
- **Remote resources.** HTML or Office input that references remote images or stylesheets may cause
the engine to fetch them while loading. Run the server without network egress if inputs are untrusted.
- **macOS CI.** Integration tests gate on Linux and Windows; the family-wide macOS runner hang is tracked
separately.
## Usage with Docker Compose
```bash
cd docker
docker compose up
```
Edit `docker/docker-compose.yml` to point the volume at your documents folder.
## Documentation & guides
Step-by-step deployment guides and a published-package integration test suite live in the companion
repo [**GroupDocs.Editor.Mcp.Tests**](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests):
- [Install from NuGet](https://github.com/groupdocs-editor/GroupDocs.Editor.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-editor/GroupDocs.Editor.Mcp.Tests/blob/master/how-to/02-run-via-docker.md)
- [Verify on the MCP registry](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests/blob/master/how-to/03-verify-mcp-registry.md)
- [Use with Claude Desktop](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests/blob/master/how-to/04-use-with-claude-desktop.md)
- [Use with VS Code / GitHub Copilot](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests/blob/master/how-to/05-use-with-vscode-copilot.md)
- [Run the integration tests](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests/blob/master/how-to/06-run-integration-tests.md)
- [Use with Cursor](https://github.com/groupdocs-editor/GroupDocs.Editor.Mcp.Tests/blob/master/how-to/07-use-with-cursor.md)
That repo exercises every advertised tool against the published package (dnx on Linux, Windows and
macOS) and the Docker image, reading every edit back through the server.
## License
MIT — see [LICENSE](LICENSE)
<!-- mcp-name: io.github.groupdocs-editor/groupdocs-editor-mcp -->
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues