groupdocs-parser-mcp

GroupDocs.Parser MCP Server

MCP server that exposes GroupDocs.Parser 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 host path in the volume mount after install; an empty GROUPDOCS_LICENSE_PATH runs in evaluation mode.

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

This product ships via Docker (GHCR) only. GroupDocs.Parser's managed DLL embeds ~234 MB of ONNX models, so the packed tool exceeds NuGet.org's 250 MB limit - so dnx and dotnet tool install are not available for it. When upstream ships a slimmer engine that packs under the limit, the standard NuGet flow returns (see the revert notes in .github/workflows/publish_prod.yml).

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

Images are multi-arch (linux/amd64 + linux/arm64), tagged latest plus an immutable version tag per release (e.g. :26.10.2). To pin, replace :latest with the version tag - recommended for shared configs and CI.

Linux: run the container as your user

The image runs as a non-root user (uid 1654). On Linux a mounted folder keeps its host owner, so a folder you own is read-only inside the container and extract_images cannot save its files — the error ends with "Fix: the server cannot write to the output folder". Add --user so the container writes as you:

docker run --rm -i --user "$(id -u):$(id -g)" \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-parser/parser-net-mcp:latest

MCP client configs (JSON) do not run a shell, so put the numbers in directly — id -u and id -g print them, typically 1000: "args": ["run", "--rm", "-i", "--user", "1000:1000", "-v", …]. Read-only tools (extract_text, extract_tables, extract_metadata, extract_barcodes, get_document_info) work without it. Docker Desktop on Windows and macOS does not need this.

Available MCP Tools

Tool	Description
extract_text	Extracts plain text from a document (whole document or a single page). Truncates very large outputs.
extract_images	Extracts all embedded images and saves them to storage as <basename>_image<N>.<ext> files
extract_metadata	Extracts metadata (author, title, dates, custom properties, EXIF, XMP, IPTC) and returns it as JSON
extract_tables	Extracts tables from a document as Markdown (default — renders in chat) or structured JSON
extract_barcodes	Detects all barcodes / QR codes and returns their decoded values, types, and positions as JSON
get_document_info	Returns the file type, page count, and size of a document as JSON (without modifying it)
get_license_status	Reports the active licensing mode (evaluation / licensed / metered), the engine version, and — under metered — the consumed quantity and credit. Processes no document.

All tools support PDF, DOCX, XLSX, PPTX, HTML, EPUB, MSG, EML, JPG, PNG, TIFF, and 50+ more document and image formats.

Example prompts for AI agents

Copy any of these into Claude Desktop, Cursor, or GitHub Copilot Chat after the server is connected.

1. Get a document's structure: "How many pages does invoice.pdf have, and what format is it?"
2. Pull a text snippet: "Extract the text from page 2 of contract.docx."
3. Mine the metadata: "What's the author and creation date of report.xlsx?"
4. Read a structured table: "Pull the line items table out of invoice.pdf as Markdown."
5. Scan for barcodes: "Are there any QR codes in shipping-label.png? If so, what do they decode to?"

Licensing

The MCP server itself is MIT; the underlying GroupDocs.Parser engine requires a license for production use. Without one the server runs in evaluation mode, and the limits bite hard for extraction — the output looks valid and is silently incomplete:

• Text extraction: only the first 1,600 characters and 20 lines per file, and only the first 5 pages, sheets or slides. Formatted-text and structure extraction add a 20-row cap for spreadsheets.
• Metadata extraction: only 5 properties per file.
• Only 100 files per session, and outputs carry evaluation marks.
• Full list: evaluation limitations.

There are two ways to license the server.

License file — mount your GroupDocs.Parser.lic (or GroupDocs.Total.lic) into the container and point GROUPDOCS_LICENSE_PATH at it, as in the Claude Desktop example above. 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. It processes no document and changes nothing, so it is the cheapest way to confirm a setup before a real run.

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 — the names alone, so the keys never appear in the command line:

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

• 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 (used by extract_images)	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_LICENSE_PATH	Path to a GroupDocs license file, as seen inside the container. Ignored when metered keys are set	(evaluation mode)
GROUPDOCS_METERED_PUBLIC_KEY	Metered (pay-per-use) public key. Needs the private key too; takes precedence over GROUPDOCS_LICENSE_PATH	(unset)
GROUPDOCS_METERED_PRIVATE_KEY	Metered private key. Secret — pass it from the environment, never from a committed config	(unset)

Usage with Claude Desktop

{
  "mcpServers": {
    "groupdocs-parser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/documents:/data", "ghcr.io/groupdocs-parser/parser-net-mcp:latest"]
    }
  }
}

To use a license, add "-v", "/path/to/license-folder:/license", "-e", "GROUPDOCS_LICENSE_PATH=/license/GroupDocs.Total.lic" before the image name. To pin a version, replace :latest with the release tag.

Usage with VS Code / GitHub Copilot

Use the Install in VS Code button above, or add to .vscode/mcp.json (also in install/generated/vscode-mcp.json):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Base folder for input and output files.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-parser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "${input:storage_path}:/data", "ghcr.io/groupdocs-parser/parser-net-mcp:latest"]
    }
  }
}

Usage with Docker Compose

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.Parser.Mcp.Tests:

• Install from NuGet
• Run via Docker
• Verify on the MCP registry
• Use with Claude Desktop
• Use with VS Code / GitHub Copilot
• Run the integration tests

License

MIT — see LICENSE