GroupDocs.Parser MCP sunucusu

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/.

Requires .NET 10 SDK.

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

dnx GroupDocs.Parser.Mcp --yes

Pulls the latest stable release on every invocation. To pin to a specific version (recommended for shared configs and CI), append @<version>:

dnx GroupDocs.Parser.Mcp@26.11.0 --yes

Or install as a global dotnet tool:

dotnet tool install -g GroupDocs.Parser.Mcp
groupdocs-parser-mcp

The first launch downloads ~230 MB, once. The engine carries its table and barcode models, so the tool ships as one package per platform (win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64) and dnx picks the one for your machine. Later launches use the NuGet cache. If your MCP client times out on that first start, run the dnx command once in a terminal, then restart the client.

Or run via Docker:

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.11.0). To pin, replace :latest with the version tag - recommended for shared configs and CI. Versions 26.10.2 and earlier were published only as Docker images.

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.

Native prerequisites

When you run the server natively (via dnx or the global dotnet tool) on Linux, the engine's image-extraction and barcode paths need two native libraries:

Platform	Setup
Windows	Nothing — GDI+ is built into the OS.
Linux	sudo apt-get install -y libgdiplus libfontconfig1
macOS	brew install mono-libgdiplus if a tool reports DllNotFoundException: libgdiplus
Docker	Nothing — the image already bundles them.

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 — point GROUPDOCS_LICENSE_PATH at your GroupDocs.Parser.lic (or GroupDocs.Total.lic). With Docker, mount the file into the container and use the path as seen inside it (see Usage with Claude Desktop). 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 (under Docker, 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": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Parser.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents"
      }
    }
  }
}

To pin to a specific version, replace "GroupDocs.Parser.Mcp" with "GroupDocs.Parser.Mcp@26.11.0" in args. Pinning is recommended for shared / committed configs to avoid surprise upgrades.

With Docker instead:

{
  "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

NuGet.org generates a ready-to-use mcp.json snippet on the package page. Copy it directly into your .vscode/mcp.json.

Alternatively, use the Install in VS Code button above, or add manually to .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Base folder for input and output files.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-parser": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Parser.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "${input:storage_path}"
      }
    }
  }
}

Same pinning rule as above — swap "GroupDocs.Parser.Mcp" for "GroupDocs.Parser.Mcp@26.11.0" to lock to a specific release. For Docker, use "command": "docker" with the args from the Claude Desktop example.

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 — dnx, global tool, pinned vs always-latest
• Run via Docker
• Verify on the MCP registry
• Use with Claude Desktop
• Use with VS Code / GitHub Copilot
• Run the integration tests

That repo also exercises every advertised tool against the published NuGet packages on Linux, macOS, and Windows, and against the GHCR image, in CI.

License

MIT — see LICENSE