Nutrient DWS MCP Server について
Nutrient DWS MCP Serverは、AIアシスタントからNutrient DWSの文書処理・抽出APIを利用するためのローカルMCPサーバーです。このリポジトリはサポート終了となり、Nutrientのホスト型MCPサーバーへの移行を案内しています。
主な機能
- 01文書の変換、編集、結合
- 02OCR、墨消し、電子署名
- 03文書の構造化データ解析
- 04スキーマ指定の引用付き項目抽出
- 05サンドボックス内のファイル操作と利用状況確認
活用シーン
- 01PDFやOffice文書を別形式に変換
- 02スキャン文書から多言語テキストを認識
- 03契約書への署名と機密情報の墨消し
- 04請求書の項目をページ引用付きで抽出
MCP 対応
stdio経由で文書処理とデータ抽出のツールをMCPクライアントに提供します。このローカル実装はサポート終了で、READMEはNutrientのホスト型MCPサーバーへの接続を推奨しています。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
npx -y @nutrient-sdk/dws-mcp-serverNUTRIENT_DWS_API_KEYシークレットNutrient DWS API key. Optional for local desktop use (browser sign-in on first request); required for CI or headless environments.NUTRIENT_DWS_EXTRACTION_API_KEYシークレットData Extraction API key (starts with pdf_live_), needed for parse_document and extract_fields in static-key mode. OAuth covers both products.SANDBOX_PATHLocal directory the server is allowed to read and write documents in.LOG_LEVELMinimum logging level; defaults to info.MCP_LOG_FILELog file path; defaults to a temporary file in stdio mode.ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
7掲載時のツール一覧 · 3 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| outputPath | string | はい | 出力ファイルのパス。(必要な場合)サンドボックスが有効ならサンドボックスのパスに解決され、そうでなければローカルファイルシステムのパスに解決されます。 |
| instructions | object | はい | 構築手順。 |
| instructions.parts | array | はい | 構築するドキュメントの部分。 |
| instructions.output | any | いいえ | 出力形式の設定。PDF、PDF/A、PDF/UA、画像、JSON コンテンツ、Office ドキュメント形式、HTML、Markdown に対応しています。 |
| instructions.actions | array | いいえ | 各部分からドキュメントを構築した後に実行する操作。 |
詳細
Nutrient DWS MCP サーバー
重要
このローカル MCP サーバーはサポートを終了しました。代わりに Nutrient MCP をご利用ください。
Nutrient は現在、MCP サーバーを
https://mcp.nutrient.io/mcpでホストしています。この URL を MCP クライアントに追加し、Nutrient アカウントでサインインしてください。インストールも API キーもサンドボックスフォルダーも必要ありません。# Claude Code claude mcp add --transport http --scope user nutrient https://mcp.nutrient.io/mcp # 次に /mcp を実行し、nutrient を選択して Authenticate を選びます # Codex codex mcp add nutrient --url https://mcp.nutrient.io/mcp && codex mcp login nutrientClaude アプリでは、
https://mcp.nutrient.io/mcpをカスタムコネクターとして追加してください。切り替えるには、クライアント設定から@nutrient-sdk/dws-mcp-serverを削除し、URL を追加します。このリポジトリは参考用としてのみ公開されています。新機能や修正は追加されません。

AI エージェントがドキュメントを生成、読み取り、抽出、処理、署名できるようにします。
説明
AI アシスタントを Nutrient Document Web Service (DWS) の Processor API および Data Extraction API に接続する Model Context Protocol(MCP)サーバーです。自然言語を通じて、ドキュメントの作成、編集、変換、デジタル署名、OCR、墨消しに加え、構造化データの抽出(バウンディングボックスと信頼度を含む型付き JSON、またはフィールドごとの引用付きスキーマに基づくフィールド抽出)を実行できます。
機能
- Claude Desktop やその他の MCP 対応クライアント向けのローカル stdio MCP サーバー
- Nutrient API を使用する最初のリクエスト時にブラウザー経由で OAuth を実行。CI やヘッドレス環境では、オプションで API キーにフォールバックできます
- ドキュメントの変換、OCR、墨消し、透かしの追加、注釈のフラット化、デジタル署名(Processor API)
- データ抽出(Data Extraction API):ドキュメント全体を Markdown または空間 JSON に解析した後、フィールドごとの引用付きで、指定した JSON スキーマに名前付きフィールドを抽出します。解析モードは 4 種類です。
text(1 クレジット/ページ、OCR なし)、structure(1.5)、understand(9、デフォルト)、agentic(18、VLM) - 出力パスを明示する、サンドボックスを考慮したローカルファイル処理
- DWS のクレジットと使用状況を確認する読み取り専用のアカウント照会
できること
設定が完了すると、自然言語でドキュメントを処理できます(あなた自身でも、AI エージェントでも実行できます)。
あなた: 「report-q1.pdf と report-q2.pdf を 1 つのドキュメントに結合して」 AI: 「完了しました。両方のレポートを combined-report.pdf に結合しました(全 24 ページ)。」
あなた: 「application.pdf からすべての社会保障番号とメールアドレスを墨消しして」 AI: 「社会保障番号 5 件とメールアドレス 3 件を検出して墨消ししました。墨消し済みファイルは application-redacted.pdf として保存されています。」
あなた: 「この契約書に 3 ページ目で見える署名を付けて、デジタル署名して」 AI: 「PAdES 準拠のデジタル署名を contract.pdf に適用しました。署名済みドキュメントは contract-signed.pdf として保存されています。」
あなた: 「この PDF を Markdown に変換して」 AI: 「ドキュメントから抽出した Markdown の内容はこちらです……」
あなた: 「このスキャン済みドキュメントにドイツ語の OCR を実行して、テキストを抽出して」 AI: 「ドイツ語の OCR でスキャンを処理しました。抽出したテキストはこちらです……」
あなた: 「invoice-0341.pdf から仕入先、請求書番号、合計金額、支払期日を、引用付きで抽出して」 AI: 「4 つのフィールドを JSON で示します。各値には、抽出元のページとバウンディングボックスが記載されています……」
インストール
Claude Desktop を使用している場合は、Claude Desktop の「設定」→「拡張機能」からインストールしてください。ローカルで開発している場合は、以下の手動セットアップを使用してください。
Claude Desktop の MCPB 拡張機能では、サンドボックスディレクトリのデフォルトが ~/Documents/Nutrient に設定されています。このディレクトリは拡張機能の設定で変更できます。この欄を空にすると、サンドボックスによる制限なしでサーバーが起動するため、ユーザーアカウントからアクセス可能な任意のパスでファイル操作を行えます。
1. Nutrient アカウントを作成する
nutrient.io/api から無料で登録してください。
ローカルのデスクトップで使用する場合は、NUTRIENT_DWS_API_KEY を省略し、Nutrient API を使用する最初のリクエスト時にブラウザーでのサインインを完了する方法を推奨します。CI、ヘッドレス環境、またはスクリプトによるセットアップでは、ダッシュボードで API キーを作成し、NUTRIENT_DWS_API_KEY を設定してください。
2. AI クライアントを設定する
プラットフォームを選択して、設定を追加してください。
Claude Desktop
「設定」→「開発者」→「設定を編集」を開き、次を追加してください。
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
プロジェクトのルートに .cursor/mcp.json を作成してください。
{
"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
~/.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)
プロジェクト内に .vscode/mcp.json を作成するか、ユーザーの mcp.json プロファイルに同じサーバー定義を追加してください。
{
"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"
},
},
},
}
その他の MCP クライアント
MCP に対応するクライアントであれば、stdio トランスポートを使用して接続できます。
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. AI クライアントを再起動する
新しい MCP サーバーの設定を反映するため、アプリケーションを再起動してください。
4. ドキュメントの処理を開始する
ドキュメントをサンドボックスディレクトリに置き、プロンプトではファイル名またはパスを明示してください。曖昧なファイル参照の依頼よりも、パスを明示するほうが安全で信頼性も高くなります。
利用可能なツール
| ツール | 説明 |
|---|---|
document_processor | 変換、OCR、透かし、回転、注釈のフラット化、墨消しのワークフローに対応したドキュメント処理 |
parse_document | 構造化データの抽出(DWS Data Extraction API):バウンディングボックスと信頼度を含む型付き JSON 要素、またはドキュメント全体の Markdown |
extract_fields | スキーマに基づくフィールド抽出(DWS Data Extraction API):定義した JSON 形式に、指定したフィールドを項目ごとの引用情報付きで抽出 |
document_signer | CMS / PKCS#7 および CAdES 署名による PDF 署名と、可視または不可視の外観オプション |
ai_redactor | 名前、住所、SSN、メールアドレス、カスタム条件などの機密情報を検出し、恒久的に削除する AI による墨消し |
check_credits | 現在の DWS クレジットと使用状況を読み取り専用で確認します。ドキュメントの内容はアップロードされません |
sandbox_file_tree | 設定済みのサンドボックスディレクトリ内にあるファイルの読み取り専用ビュー |
directory_tree | サンドボックスモードが無効な場合にローカルファイルを読み取り専用で表示します。サンドボックスモードの使用を強く推奨します |
プロンプト
sign_and_watermark— 文書にテキストの透かしを追加し、透かし入りの PDF にデジタル署名します。extract_document_fields— 名前付きフィールドを JSON オブジェクトに抽出し、必要に応じて引用情報をファイルに保持します。redact_pii— 文書から個人を特定できる情報を検出し、完全に墨消しします。parse_for_rag— 検索拡張生成と検索インデックス作成のために、文書を Markdown として解析します。office_to_pdfa— Office 文書をアーカイブ用の PDF/A ファイルに変換します。
Document Processor の機能
| 機能 | 説明 |
|---|---|
| 文書の作成 | PDF、Office 文書(DOCX、XLSX、PPTX)、画像を結合して 1 つの文書を作成します |
| 形式の変換 | PDF ↔ DOCX、画像(PNG、JPEG、WebP)、PDF/A、PDF/UA、HTML、Markdown |
| 編集 | 透かし(テキスト/画像)の追加、ページの回転、注釈のフラット化 |
| セキュリティ | 機密データ(SSN、クレジットカード番号、メールアドレスなど)の墨消し、パスワード保護、権限管理 |
| データ抽出 | 専用ツールになりました — 座標と信頼度を含む型付きの JSON/Markdown については、データ抽出(parse_document)を参照してください |
| OCR | スキャン文書向けの多言語光学文字認識 |
| 最適化 | 品質を損なわずに PDF を圧縮し、リニアライズします |
| 注釈 | XFDF 注釈のインポート、注釈のフラット化 |
| デジタル署名 | PAdES 準拠の CMS および CAdES デジタル署名(document_signer ツール経由) |
データ抽出
parse_document と extract_fields ツールは、DWS Data Extraction API をラップし、次のように認証します。
- OAuth(
NUTRIENT_DWS_API_KEYが設定されていない場合):ほかのすべてのツールで使用される同じブラウザーフロートークンで、データ抽出も利用できます。追加の設定は必要ありません。 - 静的 API キー:データ抽出は独自のテナントを持つ別製品であるため、
NUTRIENT_DWS_API_KEYの Processor キーは再利用できません。ダッシュボードで取得したデータ抽出用キーをNUTRIENT_DWS_EXTRACTION_API_KEYに設定してください。設定されていない場合、parse_documentとextract_fieldsは API を呼び出さずにエラーを返します。
parse_document は、4 種類の処理モードのいずれかを実行します。
| モード | 出力 | OCR | ページあたりのコスト |
|---|---|---|---|
text | Markdown のみ | いいえ | 1 クレジット |
structure | 空間情報または Markdown | はい | 1.5 クレジット |
understand(デフォルト) | 空間情報または Markdown | はい(AI による拡張) | 9 クレジット |
agentic | 空間情報または Markdown | はい(VLM) | 18 クレジット |
- 空間情報の出力では、境界ボックス、信頼度スコア、読み取り順序を含む型付き要素(段落、表、キーと値の領域、数式、画像、手書き文字)が返されます。要素の一覧が大きくなる場合があるため、
outputPathに書き込まれ、ツールはコンテンツを含まない概要(要素数、信頼度の低い要素のフラグ、ページのジオメトリ)を返します。 - Markdown の出力では、ドキュメント全体の Markdown がインラインで返されます。
outputPathを指定すると、そこに書き込まれます(大きなドキュメントでは推奨)。RAG や検索インデックスの作成に役立ちます。 - 両方を同時に取得:
formatの代わりにformats: ["spatial", "markdown"]を渡すと、1 回の呼び出しでoutput.elementsとoutput.markdownを取得できます。2 つ目の形式に追加料金はかかりません。空間情報のみの場合と同様に、outputPathが必要です。概要には Markdown のバイト数も含まれます。
ドキュメントは filePath(ローカルファイルシステムまたはサンドボックスからアップロード)または url(API が直接取得)のいずれかで指定できます。必ず一方だけを指定してください。
その他のオプション:
language—structure/understand/agenticモードで使用する OCR の言語です。未設定の場合、API が自動検出します。maxLanguages/maxScriptsは自動検出の対象となる言語/文字体系の最大数を制限します。これらはlanguageが未設定の場合にのみ適用されます。- Markdown のみの書式設定:
useHtmlTables(デフォルトはtrue)、enableSemanticBlockFormatting(デフォルトはtrue)、includeHeadersAndFooters(デフォルトはfalse)、extractWordsFromPictures(デフォルトはfalse)。 - 各レスポンスには、データ抽出のクレジット使用量が報告されます。これは
check_creditsで報告される Processor API クレジットとは別の残高です。
Note: インラインで返される抽出済みコンテンツ(Markdown 出力または
extract_fieldsの結果)は会話に含まれ、ホストによってログに記録される場合があります。機密文書では、空間情報をファイルに出力し、対象を絞ったextract_fields呼び出しを使用してください。
スキーマに基づく抽出(extract_fields)
parse_document がドキュメント全体を要素または Markdown に解析するのに対し、extract_fields は指定したフィールドだけを抽出します。ルートが type: "object" で properties を持つ JSON スキーマ(schema)を渡すと、レスポンスの output.data はその形状に一致します(例:{ invoiceNumber, total, lineItems: [...] })。
- サポートされるスキーマキーワード:
type、properties、required、items、description、文字列のenum、およびformat: "date"。$ref/$defsと、合成・条件キーワード(allOf/anyOf/oneOf/if/then/else)は拒否されます。スキーマは閉じられています。additionalPropertiesは自分で設定しないでください。制限:シリアライズ後 32 KB、フィールド 500 個、オブジェクトあたりのプロパティ 50 個、ネスト 5 階層、enum 値は最大 50 個です。 modeは抽出に渡す解析を実行します:structure(ページあたり 1.5 クレジット)、understand(デフォルト、ページあたり 9 クレジット)、またはagentic(ページあたり 18 クレジット)。スキーマに基づく抽出には、textモードで省略される構造解析のテキストが必要なため、textモードはありません。ページあたりの合計コストは、解析部分と固定の抽出部分を Data Extraction クレジットで合算したものです。output.dataは常にインラインで整形して返されます。これはユーザー独自のスキーマによって範囲が定められた回答です。併せて、各フィールドがどのように根拠付けられたかを示す引用の一致サマリー(id_match、id_match_multiblock、id_match_partial、fuzzy_match、not_found)と、not_foundで返されたフィールドパスの一覧も報告されます(最大 10 件。その後は「+N more」と表示)。フィールドパスはドキュメントではなくユーザーのスキーマから取得されるため、ドキュメントの内容が漏れることはありません。- フィールドごとの引用(バウンディングボックス、信頼度、一致品質)とページのジオメトリは、
outputPathが設定されている場合にのみ保持されます。これらは大きくなる可能性があり、ドキュメントを横に開いていない場合はほとんど役に立ちません。outputPathがない場合は、省略したことを示すメモが表示されます。 includeCitations(サーバーのデフォルトはtrue)、strict(デフォルトはfalse)、multimodal(デフォルトはfalse。コストとレイテンシが増加)は、明示的に設定した場合にのみ送信されます。instructions(最大 10000 文字の自由記述)を指定すると、曖昧なフィールドに関するガイダンスを追加できます。language/maxLanguages/maxScriptsは、parse_documentと同じ方法で OCR を調整します。
使用例
これらの例では、ファイルが設定済みのサンドボックス内にあり、明示的なパスを使用することを前提としています。
例 1:HTML -> PDF -> 署名
ユーザーのプロンプト: 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.
実行内容: サーバーは HTML ファイルを Nutrient にアップロードし、生成された PDF をサンドボックスに保存します。その後、その PDF に署名し、署名済みのファイルを指定された出力パスに書き戻します。
例 2:OCR 抽出
ユーザーのプロンプト: 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.
実行内容: サーバーはスキャンされた PDF を OCR のために Nutrient に送信し、抽出したテキストを Claude で返します。また、OCR 処理済みのファイルを後で使用できるよう、サンドボックスに書き込みます。
例 3:クレジットの確認 -> 処理 -> 出力の確認
ユーザーのプロンプト: 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.
実行内容: サーバーはまず読み取り専用のアカウント照会を実行し、次に DOCX ファイルを PDF に変換して、結果をサンドボックスに保存します。その後、出力ファイルが書き込まれた場所をユーザーに正確に伝えます。
例 4:スキーマに基づく引用付きフィールド抽出
ユーザープロンプト: /path/to/sandbox/invoice-0341.pdf から vendor_name、invoice_number、total_amount、due_date を抽出し、引用情報も一緒に保存してください。
処理内容: エージェントは、小さな JSON スキーマ({ "type": "object", "properties": { "vendor_name": {"type": "string"}, "invoice_number": {"type": "string"}, "total_amount": {"type": "string"}, "due_date": {"type": "string"} } })と outputPath を指定して extract_fields を呼び出します。サーバーは PDF を Data Extraction API に送信し、引用の一致状況の要約とともに、4 つの値を JSON 形式でインラインで返します。また、監査用に、フィールドごとの引用情報(ページ、バウンディングボックス、信頼度)を出力ファイルに書き込みます。
AI エージェントフレームワークでの使用
この MCP サーバーは、Model Context Protocol に対応するあらゆるプラットフォームで動作します。
- Claude Desktop — MCP を直接統合
- Cursor — MCP に対応した AI 搭載 IDE
- Windsurf — MCP に対応した AI 搭載 IDE
- VS Code + Copilot — GitHub Copilot の MCP 統合
- LangChain / LangGraph — MCP ツールアダプター経由
- OpenAI Agents SDK — MCP サーバー統合経由
- カスタムエージェント — MCP 互換システム全般
Nutrient を選ぶ理由
読み取りと書き込みのギャップ
AI はドキュメントを読み取り、理解できますが、ほとんどのツールはそこで終わってしまいます。Nutrient を使えば、AI エージェントがドキュメントを実際に操作できるようになります。結合、墨消し、署名、透かしの追加、形式変換、構造化データの抽出などが可能です。
- PDF の読み取りを超える機能 — テキスト抽出だけではありません。ドキュメントの作成、編集、変換をすべて行えます。
- 本番環境対応 — ミッションクリティカルなドキュメント処理で、何千もの企業から信頼されています。
- 標準準拠 — PAdES デジタル署名、PDF/A アーカイブ、PDF/UA アクセシビリティに対応しています。
- クラウドネイティブ — 管理が必要なインフラストラクチャはありません。ドキュメントを API に送信するだけで、結果が返されます。
- 包括的な墨消し — SSN、クレジットカード、電話番号、メールアドレス、日付などに対応する組み込みプリセットを利用できます。
- マルチフォーマット — PDF、Office ドキュメント、画像、HTML、Markdown を処理できます。
設定
サンドボックスモード(推奨)
このサーバーは、ファイル操作を特定のディレクトリに制限するサンドボックスモードに対応しています。SANDBOX_PATH 環境変数を設定して有効にします。
export SANDBOX_PATH=/path/to/sandbox/directory
npx @nutrient-sdk/dws-mcp-server
対応する CLI フラグは --sandbox <dir> と -s <dir> です。認識されないフラグが指定されると、起動時にエラーが発生します。
サンドボックスモードが有効な場合:
- 相対パスはサンドボックスディレクトリを基準に解決されます
- すべての入力ファイルパスが検証され、サンドボックス内にあることが確認されます
- 処理済みファイルはサンドボックス内に保存されます
注: サンドボックスディレクトリが指定されていない場合、サーバーはファイルパスを制限せずに動作します。セキュリティのため、サンドボックスモードを強く推奨します。
出力先
処理済みファイルは、AI が決定した場所に保存されます。出力先を指定するには、save the result to /path/to/sandbox/output/result.pdf のような明示的な出力パスを指定するか、サンドボックス内に output ディレクトリを作成してください。
認証
サーバーは、次のいずれかの方法で Nutrient DWS API(https://api.nutrient.io)に認証します。
| 方法 | 条件 | 設定 |
|---|---|---|
| API キー | NUTRIENT_DWS_API_KEY が設定されている | DWS API に Bearer トークンとして渡される静的キー |
| OAuth ブラウザーフロー | API キーが設定されていない | Nutrient OAuth の同意を得るため、Nutrient API を使用する最初のリクエスト時にブラウザーを開き、トークンをローカルにキャッシュします |
API キーが設定されていない場合、サーバーは接続状態を維持し、Nutrient API を使用する最初のリクエスト時にブラウザーベースの OAuth フローを開きます(gh auth login と同様です)。トークンは $XDG_CONFIG_HOME/nutrient/credentials.json または ~/.config/nutrient/credentials.json にキャッシュされ、自動的に更新されます。
データ抽出(parse_document、extract_fields)は、独自のテナントを持つ別の製品です。 OAuth では、1 つのトークンで両方の製品を利用できるため、追加の設定は不要です。静的 API キーの場合、NUTRIENT_DWS_API_KEY の Processor キーはデータ抽出に再利用できません。ダッシュボードで取得したデータ抽出用のキーを NUTRIENT_DWS_EXTRACTION_API_KEY に設定するか、OAuth を使用するために NUTRIENT_DWS_API_KEY を設定しないでください。
NUTRIENT_DWS_EXTRACTION_API_KEY のみを設定し(NUTRIENT_DWS_API_KEY は設定しない)、サーバーをデータ抽出専用モードで実行できます。この場合、parse_document と extract_fields は通常どおり動作しますが、Processor ツール(document_processor、document_signer、ai_redactor、check_credits)は API を呼び出さずにエラーを返します。
環境変数
| 変数 | 必須 | 説明 |
|---|---|---|
NUTRIENT_DWS_API_KEY | いいえ* | Nutrient DWS API キー(無料で取得) |
NUTRIENT_DWS_EXTRACTION_API_KEY | 静的キーを使用する場合のみ† | ダッシュボードで取得できるデータ抽出 API キー(pdf_live_ で始まります)。parse_document/extract_fields に必要です |
SANDBOX_PATH | 推奨 | ファイル操作の対象を制限するディレクトリ |
AUTH_SERVER_URL | いいえ | OAuth サーバーのベース URL(デフォルト:https://api.nutrient.io) |
CLIENT_ID | いいえ | OAuth クライアント ID。設定すると DCR をスキップし、リフレッシュトークンを再利用できます |
DWS_API_BASE_URL | いいえ | DWS API のベース URL(デフォルト:https://api.nutrient.io) |
LOG_LEVEL | いいえ | Winston ロガーのレベル(デフォルトは info)。stdio モードでは、ログは MCP_LOG_FILE に書き込まれます |
MCP_LOG_FILE | いいえ | ログファイルのパスを上書きします(デフォルト:システムの一時ディレクトリ) |
- 省略した場合、サーバーは OAuth ブラウザーフローを使用して Nutrient API に認証します。
†
NUTRIENT_DWS_API_KEYが設定されている場合にのみ関係します。データ抽出は別の製品/テナントであるため、Processor キーでは認証できません。両方の製品を 1 つのトークンで利用できる OAuth の場合は必要ありません。
データの取り扱い
ローカルに保持されるデータ
- MCP サーバープロセス、サンドボックスの適用、ファイルパスの解決は、ローカルマシン上で実行されます。
sandbox_file_treeとdirectory_treeはローカルファイルのみを調べます。ドキュメントの内容を Nutrient にアップロードすることはありません。- API キーと OAuth 認証情報は、MCP サーバーを実行しているマシン上にローカル保存されます。
Nutrient に送信されるデータ
document_processor、document_signer、ai_redactorは、要求された操作を実行するために、ドキュメントファイルと処理指示を Nutrient DWS API にアップロードします。check_creditsは認証済みのアカウント照会を送信しますが、ドキュメントファイルはアップロードしません。- 処理結果は、指定したローカルの出力パスに書き戻されます。
セキュリティに関する注意:トークンの保存
OAuth ブラウザーフローを使用する場合、アクセストークンとリフレッシュトークンは、$XDG_CONFIG_HOME/nutrient/credentials.json または ~/.config/nutrient/credentials.json に平文でキャッシュされます(パーミッションは 0600)。このファイルには、API キーと同等の認証情報が含まれています。バージョン管理にコミットしたり、共有バックアップに含めたりしないでください。
プライバシーポリシー
この拡張機能は、ローカルのサンドボックスからファイルを読み取り、ドキュメント関連のツールを呼び出すと、ドキュメントの内容と処理指示を Nutrient に送信します。また、API キーまたは OAuth 認証情報を、MCP サーバーを実行しているマシン上にローカル保存します。
Nutrient のプライバシーポリシーは、nutrient.io/legal/privacy で確認できます。
サポート
製品またはアカウントのサポートについては、nutrient.io/company/contact から Nutrient にお問い合わせください。
この MCP パッケージ固有のバグ報告や機能リクエストには、GitHub のイシューをご利用ください。
トラブルシューティング
認証をリセットして初期状態に戻す
OAuth 認証が機能しなくなった場合は、キャッシュされたトークンファイルを削除して、最初からやり直してください。
rm "${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.json"
次回のツール呼び出し時に、サーバーが自動的に新しいクライアントを登録し、同意を求めるブラウザーを開きます。
よくある質問
Claude Desktop にサーバーが表示されませんか?
- Node.js 18+ がインストールされていることを確認してください(
node --version)。 - OS に対応した設定ファイルのパスが正しいことを確認してください。
- Claude Desktop を完全に再起動してください(タスクマネージャー/アクティビティモニタを確認してください)。
OAuth ログイン用のブラウザーが開きませんか?
- ヘッドレス環境やリモート環境(SSH、Docker、CI)では、この現象が発生します。代わりに
NUTRIENT_DWS_API_KEYを設定してください。API キーが設定されている場合、サーバーはブラウザーフローをスキップします。 - macOS では、「システム設定」→「デスクトップと Dock」→「デフォルトの Web ブラウザ」で、デフォルトのブラウザーが設定されていることを確認してください。
アップグレード後に再度サインインを求められますか?
- Data Extraction(
parse_document、extract_fields)に対応するため、サーバーはより広い OAuth スコープをリクエストするようになりました。これにより、1 つのトークンで Processor と Data Extraction の両製品を利用できます。以前のバージョンでキャッシュされたトークンにはこのスコープが含まれていないため、次回のツール呼び出し時に、サーバーはもう一度だけ同意を求めます。これは想定された動作で、一度限りです。新しいトークンは通常どおりキャッシュされ、更新されます。 - ヘッドレス環境や CI 環境で、この一度限りの同意のためにブラウザーを開けない場合は、
NUTRIENT_DWS_API_KEY(Data Extraction の場合はNUTRIENT_DWS_EXTRACTION_API_KEYも)を設定して、OAuth フローをスキップしてください。
「Token exchange failed」または「OAuth authorization failed」と表示されますか?
${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.jsonを削除して、もう一度お試しください。- カスタムの
AUTH_SERVER_URLを使用している場合は、サーバーに接続できることと、その/oauth/tokenエンドポイントが動作していることを確認してください。
「Dynamic client registration failed」と表示されますか?
- カスタムの
AUTH_SERVER_URLを使用している場合は、接続できることを確認してください。 - カスタム認証サーバーが、その
/oauth/registerエンドポイントで RFC 7591 の Dynamic Client Registration に対応していることを確認してください。
「API key invalid」というエラーが表示されますか?
- dashboard.nutrient.io で API キーを確認してください。
- キーが
envセクションに正しく設定されていること(余分な空白がないこと)を確認してください。
トークンの期限が切れ、更新にも失敗しますか?
- サーバーは、キャッシュされたリフレッシュトークンを使用して、期限切れのトークンを自動的に更新します。更新に失敗した場合(例:リフレッシュトークンが取り消された場合)は、
${XDG_CONFIG_HOME:-$HOME/.config}/nutrient/credentials.jsonを削除してください。次回の呼び出し時に、サーバーがブラウザー経由で再認証します。
ファイルが見つかりませんか?
SANDBOX_PATHが既存のディレクトリを指していることを確認してください。- ドキュメントがサンドボックスディレクトリ内にあることを確認してください。
- アシスタントに設定済みのサンドボックスを調べるよう依頼するか、サンドボックスディレクトリを直接確認してください。
コントリビューション
コントリビューションガイドラインについては、CONTRIBUTING.md をご覧ください。
ライセンス
MIT License — 詳細については LICENSE をご覧ください。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。