You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Give AI agents the power to process, sign, and transform documents.**
12
12
13
+
## Description
14
+
13
15
A Model Context Protocol (MCP) server that connects AI assistants to the [Nutrient Document Web Service (DWS) Processor API](https://www.nutrient.io/api) — enabling document creation, editing, conversion, digital signing, OCR, redaction, and more through natural language.
14
16
17
+
## Features
18
+
19
+
- Local stdio MCP server for Claude Desktop and other MCP-compatible clients
20
+
- Browser-based OAuth on the first request that uses the Nutrient API, with optional API-key fallback for CI and headless environments
21
+
- Document conversion, OCR, extraction, redaction, watermarking, annotation flattening, and digital signing
22
+
- Sandbox-aware local file handling with explicit output paths
23
+
- Read-only account lookup for DWS credits and usage
24
+
15
25
## What You Can Do
16
26
17
27
Once configured, you (or your AI agent) can process documents through natural language:
@@ -31,12 +41,16 @@ Once configured, you (or your AI agent) can process documents through natural la
31
41
**You:**_"OCR this scanned document in German and extract the text"_
32
42
**AI:**_"I've processed the scan with German OCR. Here's the extracted text..."_
33
43
34
-
## Quick Start
44
+
## Installation
35
45
36
-
### 1. Get a Nutrient API Key
46
+
Once this extension is listed, install it from Claude Desktop Settings -> Extensions. Until the directory listing is live, use the manual setup below.
47
+
48
+
### 1. Create a Nutrient Account
37
49
38
50
Sign up for free at [nutrient.io/api](https://dashboard.nutrient.io/sign_up/).
39
51
52
+
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`.
53
+
40
54
### 2. Configure Your AI Client
41
55
42
56
Choose your platform and add the configuration:
@@ -56,12 +70,13 @@ Open Settings → Developer → Edit Config, then add:
56
70
"command":"npx",
57
71
"args": ["-y", "@nutrient-sdk/dws-mcp-server"],
58
72
"env": {
59
-
"NUTRIENT_DWS_API_KEY":"YOUR_API_KEY_HERE",
60
73
"SANDBOX_PATH":"/your/sandbox/directory",
61
74
// "C:\\your\\sandbox\\directory" for Windows
62
-
},
63
-
},
64
-
},
75
+
// Optional for CI or headless usage:
76
+
// "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
77
+
}
78
+
}
79
+
}
65
80
}
66
81
```
67
82
@@ -79,12 +94,13 @@ Create `.cursor/mcp.json` in your project root:
79
94
"command":"npx",
80
95
"args": ["-y", "@nutrient-sdk/dws-mcp-server"],
81
96
"env": {
82
-
"NUTRIENT_DWS_API_KEY":"YOUR_API_KEY_HERE",
83
97
"SANDBOX_PATH":"/your/project/documents",
84
98
// "C:\\your\\project\\documents" for Windows
85
-
},
86
-
},
87
-
},
99
+
// Optional for CI or headless usage:
100
+
// "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
101
+
}
102
+
}
103
+
}
88
104
}
89
105
```
90
106
@@ -102,12 +118,13 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
102
118
"command":"npx",
103
119
"args": ["-y", "@nutrient-sdk/dws-mcp-server"],
104
120
"env": {
105
-
"NUTRIENT_DWS_API_KEY":"YOUR_API_KEY_HERE",
106
121
"SANDBOX_PATH":"/your/sandbox/directory",
107
122
// "C:\\your\\sandbox\\directory" for Windows
108
-
},
109
-
},
110
-
},
123
+
// Optional for CI or headless usage:
124
+
// "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
125
+
}
126
+
}
127
+
}
111
128
}
112
129
```
113
130
@@ -116,19 +133,19 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
@@ -154,16 +174,18 @@ Restart the application to pick up the new MCP server configuration.
154
174
155
175
### 4. Start Processing Documents
156
176
157
-
Drop documents into your sandbox directory and start giving instructions!
177
+
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.
| Digital Signing | PAdES-compliant CMS and CAdES digital signatures (via document_signer tool) |
181
203
204
+
## Usage Examples
205
+
206
+
These examples assume your files live inside the configured sandbox and that you use explicit paths.
207
+
208
+
### Example 1: HTML -> PDF -> signing
209
+
210
+
**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.`
211
+
212
+
**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.
213
+
214
+
### Example 2: OCR extraction
215
+
216
+
**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.`
217
+
218
+
**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.
219
+
220
+
### Example 3: Check credits -> process -> inspect output
221
+
222
+
**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.`
223
+
224
+
**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.
225
+
182
226
## Use with AI Agent Frameworks
183
227
184
228
This MCP server works with any platform that supports the Model Context Protocol:
Supported CLI flags are `--sandbox <dir>` and `-s <dir>`. Unrecognized flags cause a startup error.
263
+
218
264
When sandbox mode is enabled:
219
265
220
266
- Relative paths resolve relative to the sandbox directory
@@ -225,7 +271,7 @@ When sandbox mode is enabled:
225
271
226
272
### Output Location
227
273
228
-
Processed files are saved to a location determined by the AI. To guide output placement, use natural language (e.g., "save the result to `output/result.pdf`") or create an `output` directory in your sandbox.
274
+
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.
229
275
230
276
### Authentication
231
277
@@ -234,27 +280,54 @@ The server authenticates to the Nutrient DWS API (`https://api.nutrient.io`) usi
234
280
| Method | When | Config |
235
281
|--------|------|--------|
236
282
|**API key**|`NUTRIENT_DWS_API_KEY` is set | Static key passed as Bearer token to DWS API |
237
-
|**OAuth browser flow**| No API key set | Opens browser for Nutrient OAuth consent, caches token locally |
283
+
|**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 |
238
284
239
-
When no API key is configured, the server opens a browser-based OAuth flow on the first tool call (similar to `gh auth login`). Tokens are cached at `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json` and refreshed automatically.
285
+
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.
|`NUTRIENT_DWS_API_KEY`| No*| Nutrient DWS API key ([get one free](https://dashboard.nutrient.io/sign_up/)) |
246
-
|`SANDBOX_PATH`| Recommended | Directory to restrict file operations to |
247
-
|`CLIENT_ID`| No | OAuth client ID. Skips DCR and enables token refresh when set |
248
-
|`DWS_API_BASE_URL`| No | DWS API base URL (default: `https://api.nutrient.io`) |
249
-
|`LOG_LEVEL`| No | Winston logger level (`info` default). Logs are written to `MCP_LOG_FILE` in stdio mode |
250
-
|`MCP_LOG_FILE`| No | Override log file path (default: system temp directory) |
291
+
|`NUTRIENT_DWS_API_KEY`| No*| Nutrient DWS API key ([get one free](https://dashboard.nutrient.io/sign_up/)) |
292
+
|`SANDBOX_PATH`| Recommended | Directory to restrict file operations to |
293
+
|`AUTH_SERVER_URL`| No | OAuth server base URL (default: `https://api.nutrient.io`) |
294
+
|`CLIENT_ID`| No | OAuth client ID. Skips DCR and enables refresh token reuse when set |
295
+
|`DWS_API_BASE_URL`| No | DWS API base URL (default: `https://api.nutrient.io`) |
296
+
|`LOG_LEVEL`| No | Winston logger level (`info` default). Logs are written to `MCP_LOG_FILE` in stdio mode |
297
+
|`MCP_LOG_FILE`| No | Override log file path (default: system temp directory) |
251
298
252
299
\* If omitted, the server uses an OAuth browser flow to authenticate with the Nutrient API.
253
300
301
+
## Data Handling
302
+
303
+
### What Stays Local
304
+
305
+
- The MCP server process, sandbox enforcement, and file path resolution run on the local machine.
306
+
-`sandbox_file_tree` and `directory_tree` inspect local files only. They do not upload document contents to Nutrient.
307
+
- API keys and OAuth credentials are stored locally on the machine running the MCP server.
308
+
309
+
### What Gets Sent to Nutrient
310
+
311
+
-`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.
312
+
-`check_credits` sends an authenticated account lookup but does not upload document files.
313
+
- Processed results are written back to the local output path you request.
314
+
254
315
### Security Note: Token Storage
255
316
256
317
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.
257
318
319
+
## Privacy Policy
320
+
321
+
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.
322
+
323
+
Nutrient's privacy policy is available at [nutrient.io/legal/privacy](https://www.nutrient.io/legal/privacy/).
324
+
325
+
## Support
326
+
327
+
For product or account support, contact Nutrient at [nutrient.io/company/contact](https://www.nutrient.io/company/contact/).
328
+
329
+
For bugs or feature requests specific to this MCP package, use [GitHub issues](https://github.com/PSPDFKit/nutrient-dws-mcp-server/issues).
330
+
258
331
## Troubleshooting
259
332
260
333
### Reset authentication to a clean state
@@ -303,7 +376,7 @@ The server will automatically register a new client and open the browser for con
303
376
304
377
- Check that `SANDBOX_PATH` points to an existing directory
305
378
- Ensure your documents are inside the sandbox directory
306
-
-Use the `sandbox_file_tree` tool to verify visible files
379
+
-Ask the assistant to inspect the configured sandbox, or inspect the sandbox directory directly
"description": "Process, sign, redact, and transform documents from Claude Desktop using Nutrient.",
7
+
"long_description": "A local Claude Desktop extension for document processing with Nutrient. It runs as a stdio MCP server, reads files from a user-selected sandbox directory, opens a browser for OAuth on the first request that uses the Nutrient API, and writes processed results back to local output paths.",
0 commit comments