Paperless-ngx

paperless-ngx-mcp

Model Context Protocol に対応した Paperless-NGX 用サーバーです。Paperless-NGX の REST API 全体を AI アシスタントに公開します。ドキュメント、タグ、連絡先、ドキュメントタイプ、カスタムフィールド、ストレージパス、保存済みビュー、共有リンクとバンドル、ワークフロー、メールアカウントとルール、ドキュメントのバージョン、メモ、ゴミ箱、タスクを扱えます。

このサーバーを選ぶ理由

• 網羅性を維持します。 CI テストでは、Paperless の /api/schema/ にあるすべてのエンドポイントをこのサーバーのツールと照合し、ラップも意図的なスキップもされていないエンドポイントが上流で追加されると失敗します。
• 実際の Paperless でテスト済みです。 エンドツーエンドテストでは、モックではなく、実行中の Paperless-ngx 3.2.1 コンテナに対してツールを実行します。
• 問題が起きる前に確認します。 すべての delete_* ツール、empty_trash、merge_documents_as_versions、一括 delete では confirm: true が必要です。「一致するすべてのドキュメント」を対象とした一括編集では、Paperless が黙って無視するフィルターを拒否します。また、triage_inbox プロンプトは変更案を提示し、書き込みを行う前に実行の許可を待ちます。
• 許可リストを簡単に設定できます。 動詞を先頭にしたツール名（list_*、get_*、delete_* など）は、それぞれ1つの権限ワイルドカードにまとめられます。
• 好みの方法でインストールできます。 npx、Docker イメージ、ワンクリックでインストールできる Claude Desktop 拡張機能、または公式 MCP Registry を利用できます。

互換性

Paperless-ngx 3.2 が対象です（3.2.1 でテスト済み）。古いバージョンの Paperless はサポートされていません。Paperless 2.x では [email protected] を使用してください。パッケージのメジャーバージョンは、対象とする Paperless-ngx のメジャーバージョンに対応しています。1.x および 2.x のリリースはありません。

クイックスタート

サーバーは paperless-ngx-mcp として npm で公開されています。npx で実行でき、クローンやビルドは不要です。

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://your-paperless-instance \
  --env PAPERLESS_API_KEY=your-api-token \
  -- npx -y paperless-ngx-mcp

現在のプロジェクトにのみインストールする場合は、--scope user を省略してください。その他のオプションについては、claude mcp add --help を参照してください。

Codex CLI

codex mcp add paperless \
  --env PAPERLESS_URL=https://your-paperless-instance \
  --env PAPERLESS_API_KEY=your-api-token \
  -- npx -y paperless-ngx-mcp

このコマンドは、エントリーを ~/.codex/config.toml に書き込みます。

Claude Desktop（拡張機能）

最新リリースから paperless-ngx-mcp.mcpb をダウンロードしてダブルクリックするか、設定 → 拡張機能 からインストールしてください。Claude Desktop が Paperless の URL と API トークンを尋ねます。

Claude Desktop、Cursor、Cline、その他の MCP クライアント

ボタンを使うとプレースホルダーの値が設定されます。あとからPAPERLESS_URLとPAPERLESS_API_KEYを置き換えてください。または、クライアントの MCP 設定ファイル（例：claude_desktop_config.json、~/.cursor/mcp.json、~/.config/cline/mcp.json）に以下を追加してください。

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "paperless-ngx-mcp"],
      "env": {
        "PAPERLESS_URL": "https://your-paperless-instance",
        "PAPERLESS_API_KEY": "your-api-token",
        "PAPERLESS_PUBLIC_URL": "https://your-public-domain"
      }
    }
  }
}

Docker

マルチアーキテクチャイメージ（amd64、arm64）がghcr.io/cubinet-code/paperless-ngx-mcpに公開されています。任意の MCP クライアント設定で stdio サーバーとして使う場合：

{
  "mcpServers": {
    "paperless": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PAPERLESS_URL", "-e", "PAPERLESS_API_KEY", "ghcr.io/cubinet-code/paperless-ngx-mcp"],
      "env": {
        "PAPERLESS_URL": "https://your-paperless-instance",
        "PAPERLESS_API_KEY": "your-api-token"
      }
    }
  }
}

または、長時間実行するStreamable HTTPサーバーとして使うこともできます。認証機能がないため、信頼できないネットワーク上では実行しないでください。

docker run -d -p 127.0.0.1:3000:3000 \
  -e PAPERLESS_URL=https://your-paperless-instance \
  -e PAPERLESS_API_KEY=your-api-token \
  ghcr.io/cubinet-code/paperless-ngx-mcp --http --port 3000

Paperless-NGX API トークンの取得

1. Paperless-NGX インスタンスにログインします。
2. ユーザー名（右上）をクリックし、マイプロフィールを選択します。
3. 円形の矢印ボタンをクリックして、新しいトークンを生成します。

設定

変数	必須	用途
PAPERLESS_URL	はい	MCP サーバーが Paperless-NGX との通信に使用するベース URL です。
PAPERLESS_API_KEY	はい	API トークンです（上記を参照）。
PAPERLESS_PUBLIC_URL	いいえ	アシスタントがドキュメントへのブラウザーリンクを作成するときに使用する公開 URL です。指定しない場合はPAPERLESS_URLが使用されます。

CLI フラグ（--baseUrl、--token、--publicUrl、--http、--port、および HTTP のセッション制限）は、環境変数より優先されます。

使用例

Claude（または MCP 対応のアシスタント）に依頼できること：

• 「'Invoice'タグが付いたすべてのドキュメントを表示して」
• 「'tax return'を含むドキュメントを検索して」
• 「#FF0000の色で'Receipts'という新しいタグを作成して」
• 「ドキュメント#123をダウンロードして」
• 「すべての取引先を一覧表示して」
• 「'Bank Statement'という新しいドキュメントタイプを作成して」
• 「ゴミ箱を空にして」
• 「保留中の取り込みタスクを表示して」
• 「取引先'ACME GmbH (mail)'のすべてのドキュメントを'ACME GmbH'に移動して」
• 「ドキュメント#55からパスワードを削除し、ロック解除したファイルを新しいバージョンとして保持して」
• 「アップロードされた銀行取引明細書の PDF パスワードを削除するワークフローを作成して」
• 「送信者ごとに新しい取引先を作成しているメールルールはどれ？」

利用可能なツール

サーバーは12のドメインにわたるツールを登録します。

ドキュメント

list_documents、get_document、get_document_content、search_documents、download_document、download_documents_bulk、get_document_thumbnail、get_document_preview、get_document_history、get_document_metadata、update_document、post_document、email_document、edit_documents_bulk、delete_document、search_autocomplete、get_document_suggestions、get_document_ai_suggestions、get_next_asn、upload_document_version、update_document_version、delete_document_version、merge_documents_as_versions

タグ

list_tags、get_tag、create_tag、update_tag、delete_tag、edit_tags_bulk

取引先

list_correspondents、get_correspondent、create_correspondent、update_correspondent、delete_correspondent、edit_correspondents_bulk

ドキュメントタイプ

list_document_types、get_document_type、create_document_type、update_document_type、delete_document_type、edit_document_types_bulk

カスタムフィールド

list_custom_fields、get_custom_field、create_custom_field、update_custom_field、delete_custom_field、edit_custom_fields_bulk

ストレージパス

list_storage_paths, get_storage_path, create_storage_path, update_storage_path, delete_storage_path, test_storage_path

保存済みビュー

list_saved_views, get_saved_view, create_saved_view, update_saved_view, delete_saved_view

共有リンク

list_share_links, list_document_share_links, get_share_link, create_share_link, delete_share_link, list_share_link_bundles, get_share_link_bundle, create_share_link_bundle, rebuild_share_link_bundle, delete_share_link_bundle

ワークフロー

list_workflows, get_workflow, create_workflow, update_workflow, delete_workflow, list_workflow_actions, get_workflow_action, create_workflow_action, update_workflow_action, delete_workflow_action, list_workflow_triggers, get_workflow_trigger, create_workflow_trigger, update_workflow_trigger, delete_workflow_trigger

メール

list_mail_accounts, get_mail_account, create_mail_account, update_mail_account, delete_mail_account, test_mail_account, process_mail_account, list_mail_rules, get_mail_rule, create_mail_rule, update_mail_rule, delete_mail_rule

システム／メモ／ゴミ箱／タスク

get_statistics, get_system_status, get_filing_options, list_document_notes, create_document_note, delete_document_note, list_trash, restore_from_trash, empty_trash, list_tasks, list_active_tasks, get_task_status_counts, get_task_summary, acknowledge_tasks

ツールの命名規則（権限許可リスト向け）

ツール名は動詞が先頭に来るため、ワイルドカードベースの権限ルールで操作ごとに簡潔にグループ化できます。

ワイルドカード	対象
mcp__paperless__list_*	すべての一覧／インデックスの読み取り
mcp__paperless__get_*	すべての単一項目の読み取り
mcp__paperless__search_*	全文検索とオートコンプリート
mcp__paperless__download_*	download_document および download_documents_bulk
mcp__paperless__create_*	すべての作成エンドポイント
mcp__paperless__update_*	項目ごとの PATCH 更新
mcp__paperless__edit_*_bulk	エンティティ種別をまたぐすべての一括編集操作
mcp__paperless__delete_*	⚠️ 破壊的操作 — システム全体の削除
mcp__paperless__test_*	ドライランチェック：test_storage_path、test_mail_account
mcp__paperless__upload_*	upload_document_version
mcp__paperless__rebuild_*	rebuild_share_link_bundle
mcp__paperless__merge_*	⚠️ merge_documents_as_versions — 統合されたドキュメントは個別には存在しなくなります
mcp__paperless__process_*	process_mail_account — メールを取得してルールを実行します（サーバー上のメールを削除または移動する場合があります）

そのため、読み取り専用の許可リストは次のとおりです：list_*、get_*、search_*、download_*、test_*。破壊的操作を除く書き込みアクセスには、create_*、update_*、edit_*_bulk、upload_*、rebuild_*、post_document、email_document、restore_from_trash、acknowledge_tasks を追加します。delete_*、merge_*、process_*、empty_trash には、ユーザーによる明示的な承認が必要です。

プロンプト

サーバーは MCP プロンプト（Claude Code などのクライアントでスラッシュコマンドとして表示される、再利用可能なパラメーター付きの指示。例：/mcp__paperless__triage_inbox）も登録します。

triage_inbox

受信トレイのトリアージをアシスタントに順を追って案内します。既存のタグ／対応者／ドキュメント種別を収集し、受信トレイ内の各ドキュメントに付与するメタデータを既存の項目を優先して提案し、確認用の表を表示します。ユーザーが apply と返信した後にのみ変更を適用します。新しい対応者／種別／タグには (NEW) の印が付くため、作成前に取り消すことができます。

引数：

• limit（省略可、デフォルト：25）：1 回の処理でトリアージする受信トレイ内のドキュメントの最大数。

注目すべきツールの詳細

edit_documents_bulk

複数のドキュメントに対して一括操作を実行します。

パラメーター：

• 選択方法：documents（ID の配列）、または all: true と、任意の excluded_documents を含む filters。filters には、correspondent__id、tags__id__all、document_type__id、title_content、query など、Paperless のドキュメントフィルター名を指定します。list_documents のツール引数ではありません。Paperless が認識しないキーは拒否されます（拒否しない場合、すべてのドキュメントが選択されてしまいます）。プレビュークエリで無効な値を検出し、結果には matched_documents が含まれます。all: true は merge、split、delete_pages、edit_pdf、remove_password ではサポートされていません。
• method：set_correspondent、set_document_type、set_storage_path、add_tag、remove_tag、modify_tags、modify_custom_fields、delete、reprocess、set_permissions、merge、split、rotate、delete_pages、edit_pdf、remove_password のいずれか
• メソッド固有のパラメーター：correspondent、document_type、storage_path、tag、add_tags、remove_tags、add_custom_fields、remove_custom_fields、set_permissions、owner、merge、metadata_document_id、delete_originals、pages、degrees、operations、update_document、include_metadata、password、delete_original、remote_ocr

// Add a tag to multiple documents
edit_documents_bulk({ documents: [1, 2, 3], method: "add_tag", tag: 5 })

// Merge documents
edit_documents_bulk({
  documents: [6, 7, 8],
  method: "merge",
  metadata_document_id: 6,
  delete_originals: true,
})

// Split a document into parts
edit_documents_bulk({ documents: [9], method: "split", pages: "[1-2,3-4,5]" })

// Modify multiple tags at once
edit_documents_bulk({
  documents: [10, 11],
  method: "modify_tags",
  add_tags: [1, 2],
  remove_tags: [3, 4],
})

// Move every document from a duplicate correspondent (12) to the canonical one (34)
edit_documents_bulk({ all: true, filters: { correspondent__id: 12 }, method: "set_correspondent", correspondent: 34 })

// Unlock a password-protected PDF, keeping the result as a new version
edit_documents_bulk({ documents: [55], method: "remove_password", password: "…", update_document: true })

Paperless は、ドキュメントをスキップした場合（最新バージョンが暗号化されていない場合）や、パスワードが間違っている場合でも、remove_password に対して OK を返します。そのため、実行後にドキュメントの versions を確認してください。

ワークフロー

ワークフローとは、トリガーと、それによって実行されるアクションの組み合わせで、Paperless が実行するものです。create_workflow を使うと、1 回の呼び出しでワークフローを作成できます。単独のトリガーやアクション（create_workflow_trigger／create_workflow_action）はそれだけでは機能せず、ワークフローが更新されるたびに、Paperless によって未接続のものが削除されます。

• アクションの種類：1 割り当て、2 削除、3 メール送信、4 Webhook、5 パスワード削除、6 ゴミ箱に移動、7 リモート OCR、8 AI による提案の適用。リモート OCR には取り込み開始トリガーが必要です。AI による提案には、取り込み開始以外のトリガーが必要です。
• update_workflow は、渡した内容のみを変更します。ただし、triggers または actions のリストを指定すると、リスト全体が置き換えられます。id がある項目は更新され、ない項目は作成され、省略された項目は削除されます。get_workflow の出力は編集して、そのまま返すことができます。
• パスワード削除アクションの PDF パスワードは、常にマスクされて返されます（**********）。マスクされたリストを送り返すと、保存済みのパスワードが保持されます。新しいアクションには、実際のパスワードが必要です。
• トリガーが確認するフィルターは種類によって異なります。sources、filter_path、filter_mailrule は取り込み開始トリガー（種類 1）でのみ機能します。タグ、送信者、種類、保存先パスの各フィルター、filter_custom_field_query、コンテンツの照合は、追加／更新／スケジュール済みトリガー（種類 2～4）でのみ機能します。filter_filename はすべての種類で機能します。

ドキュメントのバージョン

upload_document_version は既存のドキュメントに新しいファイル（署名済みのコピーや修正版のスキャンなど）を追加し、merge_documents_as_versions は重複するドキュメントを 1 つにまとめます。コンテンツ、検索、ダウンロード、get_document_metadata は最新バージョンを参照しますが、page_count と get_document に表示されるファイル名は元の（ルート）バージョンのものです。現在のバージョンが読み取り可能かどうかは、get_document_content で確認してください。

単一のドキュメントの読み取りと編集

• get_filing_options は、すべてのタグ、取引先、ドキュメントタイプ、保存先パス、カスタムフィールド（ID＋名前）を1回の呼び出しで返します。IDを推測せずにファイリングできるよう、ファイリング前に一度取得してください。
• update_document の add_tags ／ remove_tags を使うと、ほかのタグに触れずに個々のタグを変更できます。tags はリスト全体を置き換えます。タグを変更すると、毎回 tag_changes: { added, removed } が返されます。
• list_documents の ids を使うと、把握済みの複数のドキュメントを1回の呼び出しで読み取れます。また、fields（get_document でも使用可能）を指定すると、たとえば ["title", "tags"] のように必要な項目だけを返せます。
• get_document_content では、長いドキュメントに対して max_chars と offset を指定できます。その場合、結果には total_chars と truncated が含まれます。Paperless はページ境界を設けずにテキストを保存するため、切り出し範囲は文字数単位です。
• search_documents は全文検索インデックスを検索します（mode は、高度な構文を使う query がデフォルト、通常の単語で検索する text、タイトルのみを検索する title）。インデックスの更新には時間がかかる場合があります。list_documents の search を使うと、データベースから直接部分一致で検索できます。

post_document

新しいドキュメントをアップロードします。

パラメーター：file、filename、およびオプションの title、created、correspondent、document_type、storage_path、tags、archive_serial_number、custom_fields、poll、poll_timeout_seconds。

file には、Base64 エンコードされた内容（どの環境でも使える汎用的な方法です。バイトデータがネットワーク経由で送信されます）、またはサーバーが自身のファイルシステムから読み取る絶対ファイルパスを指定できます。パス指定を使えるのは、MCP サーバーとファイルが同じマシンにある場合（ローカル／stdio 環境）のみです。リモートサーバーの場合は、Base64 を使用してください。

アップロードは非同期です。デフォルトでは、ツールはタスク UUID を返します（list_tasks で追跡できます）。コンシューマーの処理が完了するまで待ち、成功時は新しい document_id、失敗時はコンシューマーのエラーを1回の呼び出しで取得するには、poll: true を設定してください。poll_timeout_seconds（デフォルトは30、最大300）で待機時間の上限を設定できます。OCR に時間がかかる大きなスキャンデータでは、この値を大きくしてください。

マッチングアルゴリズム

create_tag、create_correspondent、create_document_type、create_storage_path は、matching_algorithm（0～6）を受け付けます。ワークフローのトリガーでは0～5を受け付けます（Automatic はありません）。

値	意味
0	なし
1	いずれかの単語
2	すべての単語
3	完全一致
4	正規表現
5	あいまいな単語
6	自動

Paperless-ngx 3.2 以降では、Automatic マッチングで分類器の信頼度が十分に高い場合にのみ割り当てが行われます（PAPERLESS_CLASSIFIER_MATCH_THRESHOLD、デフォルトは0.6）。また、正規表現によるマッチングは PAPERLESS_MATCH_REGEX_TIMEOUT_SECONDS（デフォルトは0.1秒）を過ぎると打ち切られます。長いドキュメントで正規表現ルールが一致しない場合は、この値を大きくしてください。

MCP サーバーの実行

stdio（デフォルト）

デフォルトのモードです。サーバーは stdio 経由で通信します。クイックスタートにあるすべての MCP クライアント設定で使用するモードです。通常、手動で実行する必要はありません。MCP クライアントが起動します。

直接実行する場合（デバッグなど）は、次のようにします。

# via env vars (recommended)
PAPERLESS_URL=http://localhost:8000 PAPERLESS_API_KEY=xxx npx -y paperless-ngx-mcp

# or via CLI flags
npx -y paperless-ngx-mcp --baseUrl http://localhost:8000 --token xxx

HTTP（Streamable HTTP トランスポート）

--http フラグを使うと、サーバーを HTTP 経由で公開できます。--port のデフォルトは 3000 です。

npx -y paperless-ngx-mcp --baseUrl http://localhost:8000 --token xxx --http --port 3000

• MCP API は、選択したポートの POST /mcp で利用でき、ステートフルモードの StreamableHTTPServerTransport によって処理されます。
• 最初のリクエスト（initialize 呼び出し）でセッションが作成され、Mcp-Session-Id ヘッダーが返されます。同じセッションを再利用するには、以降のリクエストでこのヘッダーを送り返す必要があります。トランスポートはメモリ内の Map に保持されるため、単一インスタンスでのデプロイでのみ機能します。
• GET /mcp はセッション向けのサーバー起点メッセージをストリーミングします。DELETE /mcp はセッションを終了し、Map から削除します。どちらも有効な Mcp-Session-Id ヘッダーが必要です。
• ストリーミング可能なトランスポートにまだ対応していないクライアント向けに、従来の GET /sse ＋ POST /messages による SSE トランスポートも公開されています。

セッションの上限

各セッションは独自の MCP サーバーインスタンス（約 3.5 MB）を保持し、HTTP ポートには認証がありません。そのため、セッション数には上限があります。

フラグ	環境変数	デフォルト	用途
--maxSessions	PAPERLESS_MAX_SESSIONS	50	許可される同時セッション数です。上限を超えると、initialize は HTTP 503 で拒否されます。
--sessionIdleMinutes	PAPERLESS_SESSION_IDLE_MINUTES	30	アクティビティがない状態がこの時間続くと、セッションを削除します。

GET /mcp のストリームを開いたままにしている場合も含め、クライアントが接続中であれば、アイドル状態がどれだけ続いても削除されません。実際に放棄されたセッションのみが回収されます。

セッションはメモリ上に保持されるため、--http は単一インスタンスのデプロイでのみ動作します。認証がなく、すべてのインターフェースにバインドされるため、信頼できないネットワークにポートを公開しないでください。

エラー処理

ツール呼び出しでは、次の場合に明確なエラーが返されます。

• PAPERLESS_URL または PAPERLESS_API_KEY がない、または正しくない場合
• Paperless-NGX サーバーに接続できない場合
• 基盤となる API が操作を拒否した場合 — Paperless 独自のメッセージがそのまま渡されます（例：{"non_field_errors":["password not specified"]} (HTTP 400)）。HTML のエラーページはステータス行に短縮されます
• Paperless の呼び出しが 90 秒以内に完了しない場合（ダウンロードは対象外）。タイムアウトした書き込み操作では、変更がすでに適用されている可能性があることを示す警告が表示されます
• ツールのパラメーターが検証に失敗した場合

開発

このセクションが必要なのは、サーバー自体を変更する場合のみです。エンドユーザーは代わりにクイックスタートに従ってください。クローンやビルドは不要です。

git clone https://github.com/cubinet-code/paperless-ngx-mcp.git
cd paperless-ngx-mcp
npm install        # install dependencies
npm run start      # run the server with tsx (no build step)
npm run build      # compile TypeScript to build/
npm test           # unit tests (node:test + tsx)
npm run inspect    # build, then launch @modelcontextprotocol/inspector

npm run start は、ビルド済みバイナリと同じフラグ／環境変数を受け付けます。

エンドツーエンドテスト

E2E テストでは、Docker Compose を使用して実際の Paperless-NGX コンテナーを起動します。

npm run test:e2e:up    # start the test stack (paperless + redis)
npm run test:e2e       # run the e2e suite against it
npm run test:e2e:down  # tear down and remove volumes

ghcr.io/paperless-ngx/paperless-ngx:3.2.1 に対して実行されます。

以下を使用して構築されています。

• @modelcontextprotocol/sdk — MCP サーバー SDK
• zod — スキーマ検証
• axios — HTTP クライアント（キープアライブエージェント、60 秒のアイドルタイムアウト、リクエストごとの 90 秒の期限付き）

API ドキュメント

この MCP サーバーは、Paperless-NGX REST API のエンドポイントをラップしています。基盤となる動作やフィールドの意味について詳しくは、公式 API ドキュメントを参照してください。

ライセンス

ISC。LICENSEを参照してください。