Nutrient DWS MCP Server

Give AI agents the power to process, sign, and transform documents.

Description

A Model Context Protocol (MCP) server that connects AI assistants to the Nutrient Document Web Service (DWS) Processor API — enabling document creation, editing, conversion, digital signing, OCR, redaction, and more through natural language.

Features

Local stdio MCP server for Claude Desktop and other MCP-compatible clients
Browser-based OAuth on the first request that uses the Nutrient API, with optional API-key fallback for CI and headless environments
Document conversion, OCR, extraction, redaction, watermarking, annotation flattening, and digital signing
Sandbox-aware local file handling with explicit output paths
Read-only account lookup for DWS credits and usage

What You Can Do

Once configured, you (or your AI agent) can process documents through natural language:

You: "Merge report-q1.pdf and report-q2.pdf into a single document" AI: "Done! I've merged both reports into combined-report.pdf (24 pages total)."

You: "Redact all social security numbers and email addresses from application.pdf" AI: "I found and redacted 5 SSNs and 3 email addresses. The redacted version is saved as application-redacted.pdf."

You: "Digitally sign this contract with a visible signature on page 3" AI: "I've applied a PAdES-compliant digital signature to contract.pdf. The signed document is saved as contract-signed.pdf."

You: "Convert this PDF to markdown" AI: "Here's the markdown content extracted from your document..."

You: "OCR this scanned document in German and extract the text" AI: "I've processed the scan with German OCR. Here's the extracted text..."

Installation

Install it from Claude Desktop Settings -> Extensions if you are using Claude Desktop. If you are developing locally, use the manual setup below.

1. Create a Nutrient Account

Sign up for free at nutrient.io/api.

For local desktop use, the recommended path is to omit NUTRIENT_DWS_API_KEY and complete the browser sign-in flow on the first request that uses the Nutrient API. For CI, headless environments, or scripted setups, create an API key in the dashboard and set NUTRIENT_DWS_API_KEY.

2. Configure Your AI Client

Choose your platform and add the configuration:

Claude Desktop

Open Settings → Developer → Edit Config, then add:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nutrient-dws": {
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
      "env": {
        "SANDBOX_PATH": "/your/sandbox/directory",
        // "C:\\your\\sandbox\\directory" for Windows
        // Optional for CI or headless usage:
        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "nutrient-dws": {
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
      "env": {
        "SANDBOX_PATH": "/your/project/documents",
        // "C:\\your\\project\\documents" for Windows
        // Optional for CI or headless usage:
        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "nutrient-dws": {
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
      "env": {
        "SANDBOX_PATH": "/your/sandbox/directory",
        // "C:\\your\\sandbox\\directory" for Windows
        // Optional for CI or headless usage:
        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your project, or add the same server definition to your user mcp.json profile:

{
  "servers": {
    "nutrient-dws": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
      "env": {
        "SANDBOX_PATH": "${workspaceFolder}",
        // Optional for CI or headless usage:
        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect using stdio transport:

SANDBOX_PATH=/your/path npx @nutrient-sdk/dws-mcp-server

# Optional for CI or headless usage:
NUTRIENT_DWS_API_KEY=your_key SANDBOX_PATH=/your/path npx @nutrient-sdk/dws-mcp-server

3. Restart Your AI Client

Restart the application to pick up the new MCP server configuration.

4. Start Processing Documents

Place documents in your sandbox directory and use explicit file names or paths in prompts. Explicit paths are safer and more reliable than vague file-browsing requests.

Available Tools

Tool	Description
`document_processor`	Document processing for conversions, OCR, extraction, watermarking, rotation, annotation flattening, and redaction workflows
`document_signer`	PDF signing with CMS / PKCS#7 and CAdES signatures plus visible or invisible appearance options
`ai_redactor`	AI redaction for detecting and permanently removing sensitive content such as names, addresses, SSNs, emails, and custom criteria
`check_credits`	Read-only account lookup for current DWS credits and usage. No document content is uploaded
`sandbox_file_tree`	Read-only view of files inside the configured sandbox directory
`directory_tree`	Read-only view of local files when sandbox mode is disabled. Sandbox mode is strongly recommended

Document Processor Capabilities

Feature	Description
Document Creation	Merge PDFs, Office docs (DOCX, XLSX, PPTX), and images into a single document
Format Conversion	PDF ↔ DOCX, images (PNG, JPEG, WebP), PDF/A, PDF/UA, HTML, Markdown
Editing	Watermark (text/image), rotate pages, flatten annotations
Security	Redact sensitive data (SSNs, credit cards, emails, etc.), password protection, permission control
Data Extraction	Extract text, tables, or key-value pairs as structured JSON
OCR	Multi-language optical character recognition for scanned documents
Optimization	Compress and linearize PDFs without quality loss
Annotations	Import XFDF annotations, flatten annotations
Digital Signing	PAdES-compliant CMS and CAdES digital signatures (via document_signer tool)

Usage Examples

These examples assume your files live inside the configured sandbox and that you use explicit paths.

Example 1: HTML -> PDF -> signing

User prompt: Convert /path/to/sandbox/invoice.html to PDF and save it as /path/to/sandbox/invoice.pdf. Then digitally sign /path/to/sandbox/invoice.pdf with a visible signature and save it as /path/to/sandbox/invoice-signed.pdf.

What happens: The server uploads the HTML file to Nutrient, saves the generated PDF in the sandbox, then signs that PDF and writes the signed result back to the requested output path.

Example 2: OCR extraction

User prompt: Run OCR on /path/to/sandbox/scanned-contract.pdf, return the extracted text, and save the OCR'd file as /path/to/sandbox/scanned-contract-ocr.pdf.

What happens: The server sends the scanned PDF to Nutrient for OCR, returns the extracted text in Claude, and writes the OCR-processed file back to the sandbox for later use.

Example 3: Check credits -> process -> inspect output

User prompt: Check my Nutrient credits, convert /path/to/sandbox/report.docx to PDF, save it as /path/to/sandbox/report.pdf, and then tell me where the output file was written.

What happens: The server first performs a read-only account lookup, then converts the DOCX file to PDF, saves the result in the sandbox, and tells the user exactly where the output file was written.

Use with AI Agent Frameworks

This MCP server works with any platform that supports the Model Context Protocol:

Claude Desktop — Direct MCP integration
Cursor — AI-powered IDE with MCP support
Windsurf — AI-powered IDE with MCP support
VS Code + Copilot — GitHub Copilot MCP integration
LangChain / LangGraph — Via MCP tool adapters
OpenAI Agents SDK — Via MCP server integration
Custom agents — Any MCP-compatible system

Why Nutrient?

The Read-Write Gap

AI can read and understand documents — but most tools stop there. Nutrient gives AI agents the ability to actually manipulate documents: merge, redact, sign, watermark, convert formats, extract structured data, and more.

Beyond PDF reading — Not just text extraction. Full document creation, editing, and transformation.
Production-grade — Trusted by thousands of companies for mission-critical document processing.
Standards-compliant — PAdES digital signatures, PDF/A archiving, PDF/UA accessibility.
Cloud-native — No infrastructure to manage. Send documents to the API, get results back.
Comprehensive redaction — Built-in presets for SSNs, credit cards, phone numbers, emails, dates, and more.
Multi-format — Process PDFs, Office documents, images, HTML, and Markdown.

Configuration

Sandbox Mode (Recommended)

The server supports sandbox mode that restricts file operations to a specific directory. Set the SANDBOX_PATH environment variable to enable it:

export SANDBOX_PATH=/path/to/sandbox/directory
npx @nutrient-sdk/dws-mcp-server

Supported CLI flags are --sandbox <dir> and -s <dir>. Unrecognized flags cause a startup error.

When sandbox mode is enabled:

Relative paths resolve relative to the sandbox directory
All input file paths are validated to ensure they reside in the sandbox
Processed files are saved within the sandbox

Note: If no sandbox directory is specified, the server operates without file path restrictions. Sandbox mode is strongly recommended for security.

Output Location

Processed files are saved to a location determined by the AI. To guide output placement, use explicit output paths such as save the result to /path/to/sandbox/output/result.pdf or create an output directory in your sandbox.

Authentication

The server authenticates to the Nutrient DWS API (https://api.nutrient.io) using one of:

Method	When	Config
API key	`NUTRIENT_DWS_API_KEY` is set	Static key passed as Bearer token to DWS API
OAuth browser flow	No API key set	Opens browser for Nutrient OAuth consent on the first request that uses the Nutrient API, caches token locally

When no API key is configured, the server stays connected and opens a browser-based OAuth flow on the first request that uses the Nutrient API (similar to gh auth login). Tokens are cached at $XDG_CONFIG_HOME/nutrient/credentials.json or ~/.config/nutrient/credentials.json and refreshed automatically.

Environment Variables

Variable	Required	Description
`NUTRIENT_DWS_API_KEY`	No*	Nutrient DWS API key (get one free)
`SANDBOX_PATH`	Recommended	Directory to restrict file operations to
`AUTH_SERVER_URL`	No	OAuth server base URL (default: `https://api.nutrient.io`)
`CLIENT_ID`	No	OAuth client ID. Skips DCR and enables refresh token reuse when set
`DWS_API_BASE_URL`	No	DWS API base URL (default: `https://api.nutrient.io`)
`LOG_LEVEL`	No	Winston logger level (`info` default). Logs are written to `MCP_LOG_FILE` in stdio mode
`MCP_LOG_FILE`	No	Override log file path (default: system temp directory)

* If omitted, the server uses an OAuth browser flow to authenticate with the Nutrient API.

Data Handling

What Stays Local

The MCP server process, sandbox enforcement, and file path resolution run on the local machine.
sandbox_file_tree and directory_tree inspect local files only. They do not upload document contents to Nutrient.
API keys and OAuth credentials are stored locally on the machine running the MCP server.

What Gets Sent to Nutrient

document_processor, document_signer, and ai_redactor upload the document files and processing instructions to the Nutrient DWS API so the requested operation can run.
check_credits sends an authenticated account lookup but does not upload document files.
Processed results are written back to the local output path you request.

Security Note: Token Storage

When using the OAuth browser flow, access tokens and refresh tokens are cached in plaintext at $XDG_CONFIG_HOME/nutrient/credentials.json or ~/.config/nutrient/credentials.json (permissions 0600). This file contains credentials equivalent to your API key. Do not commit it to version control or include it in shared backups.

Privacy Policy

This extension reads files from the local sandbox, sends document contents and processing instructions to Nutrient when you invoke document tools, and stores API keys or OAuth credentials locally on the machine running the MCP server.

Nutrient's privacy policy is available at nutrient.io/legal/privacy.

Support

For product or account support, contact Nutrient at nutrient.io/company/contact.

For bugs or feature requests specific to this MCP package, use GitHub issues.

Troubleshooting

Reset authentication to a clean state

If OAuth authentication stops working, delete the cached token file to start fresh:

rm "${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json"

The server will automatically register a new client and open the browser for consent on the next tool call.

FAQ

Server not appearing in Claude Desktop?

Ensure Node.js 18+ is installed (node --version)
Check the config file path is correct for your OS
Restart Claude Desktop completely (check Task Manager/Activity Monitor)

Browser doesn't open for OAuth login?

This happens in headless or remote environments (SSH, Docker, CI). Set NUTRIENT_DWS_API_KEY instead — the server skips the browser flow when an API key is configured.
On macOS, ensure a default browser is set in System Settings → Desktop & Dock → Default web browser.

"Token exchange failed" or "OAuth authorization failed"?

Delete ${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json and try again.
If using a custom AUTH_SERVER_URL, verify the server is reachable and its /oauth/token endpoint is working.

"Dynamic client registration failed"?

If using a custom AUTH_SERVER_URL, verify it is reachable.
Ensure the custom auth server supports RFC 7591 Dynamic Client Registration at its /oauth/register endpoint.

"API key invalid" errors?

Verify your API key at dashboard.nutrient.io
Ensure the key is set correctly in the env section (no extra spaces)

Token expired but refresh fails?

The server automatically refreshes expired tokens using the cached refresh token. If refresh fails (e.g., the refresh token was revoked), delete ${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json — the server will re-authenticate via the browser on the next call.

Files not found?

Check that SANDBOX_PATH points to an existing directory
Ensure your documents are inside the sandbox directory
Ask the assistant to inspect the configured sandbox, or inspect the sandbox directory directly

Contributing

Please see the contribution guidelines in CONTRIBUTING.md.

License

MIT License — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github/workflows		.github/workflows
benchmarks		benchmarks
docs		docs
resources		resources
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
autoresearch.ideas.md		autoresearch.ideas.md
autoresearch.md		autoresearch.md
autoresearch.sh		autoresearch.sh
eslint.config.mjs		eslint.config.mjs
manifest.json		manifest.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Nutrient DWS MCP Server

Description

Features

What You Can Do

Installation

1. Create a Nutrient Account

2. Configure Your AI Client

3. Restart Your AI Client

4. Start Processing Documents

Available Tools

Document Processor Capabilities

Usage Examples

Example 1: HTML -> PDF -> signing

Example 2: OCR extraction

Example 3: Check credits -> process -> inspect output

Use with AI Agent Frameworks

Why Nutrient?

The Read-Write Gap

Configuration

Sandbox Mode (Recommended)

Output Location

Authentication

Environment Variables

Data Handling

What Stays Local

What Gets Sent to Nutrient

Security Note: Token Storage

Privacy Policy

Support

Troubleshooting

Reset authentication to a clean state

FAQ

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages