Paperless-ngx ドキュメント管理
9つのドメインにわたる42個のMCPツールを使って、Paperless-ngxを操作します。
ツール一覧
ドキュメント（7個のツール）
| ツール | 操作 | 主なパラメーター |
|---|
search_documents | 全文検索 | query、page、page_size |
get_document | 詳細情報の取得 | id |
update_document | 単一ドキュメントの更新 | id、title、archive_serial_number、custom_fields、note |
delete_document_note | メモの削除 | id、note_id |
post_document | ファイルのアップロード | file_path（ローカル）またはfile（base64）、メタデータ |
download_document | ファイルをbase64で取得 | id、original（bool） |
bulk_edit_documents | 一括操作 | documents（ID）、method、パラメーター |
タグ（6個のツール）
| ツール | 操作 |
|---|
list_tags | すべてのタグ＋色＋マッチング条件 |
get_tag | IDを指定して単一のタグを取得 |
create_tag | 新しいタグを作成（自動マッチングは任意） |
update_tag | 名前／色／マッチング条件を変更 |
delete_tag | 非推奨 — bulk_edit_tagsのoperation=deleteを使用 |
bulk_edit_tags | 権限／削除の一括操作 |
取引先（5個のツール）
| ツール | 操作 |
|---|
list_correspondents | すべての取引先 |
get_correspondent | IDを指定して単一の取引先を取得 |
create_correspondent | 新しい取引先を作成（自動マッチングは任意） |
update_correspondent | 名前／マッチングルールを変更 |
bulk_edit_correspondents | 権限／削除の一括操作 |
ドキュメントタイプ（5個のツール）
| ツール | 操作 |
|---|
list_document_types | すべてのドキュメントタイプ |
get_document_type | IDを指定して単一のタイプを取得 |
create_document_type | 新しいタイプを作成（自動マッチングは任意） |
update_document_type | 名前／マッチングルールを変更 |
bulk_edit_document_types | 権限／削除の一括操作 |
ストレージパス（4個のツール）
| ツール | 操作 |
|---|
list_storage_paths | すべてのストレージパス |
create_storage_path | 新しいパステンプレート＋自動マッチング |
update_storage_path | 名前／テンプレート／マッチング条件を変更 |
bulk_edit_storage_paths | 権限／削除の一括操作 |
カスタムフィールド（4個のツール）
| ツール | 操作 |
|---|
list_custom_fields | すべてのフィールド定義＋ID |
create_custom_field | 新しいフィールドを作成（名前＋データ型） |
update_custom_field | 名前／データ型／オプションを変更 |
delete_custom_field | 1つのフィールドとすべての値を削除 |
タスク（2個のツール）
| ツール | 操作 |
|---|
get_task | post_document UUIDのステータス＋結果のドキュメントID |
list_tasks | 最近のタスクを新しい順に表示。ステータス／名前で絞り込み、最大100件 |
ゴミ箱（3 つのツール）
| ツール | 操作 |
|---|
list_trash | 完全削除待ちのソフト削除済みドキュメントを一覧表示します |
restore_from_trash | メタデータを保持したままドキュメントを復元します |
empty_trash | 完全に削除します（すべて、または特定の ID） |
メール（6 つのツール）
| ツール | 操作 |
|---|
list_mail_accounts | ポーリング対象のアカウント（認証情報は除外） |
process_mail_account | メールのポーリングをすぐに実行します |
list_mail_rules | インポート対象を決定するフィルター |
create_mail_rule | 新しいインポートルール（フィルターと割り当て） |
update_mail_rule | フィルター、割り当て、有効状態を変更します |
delete_mail_rule | ルールを削除します（今後の取り込みのみ） |
判断ツリー
ドキュメントを検索する
What do you know?
├─ Keywords/content → search_documents(query="term1 term2")
├─ Document ID → get_document(id=N)
├─ By tag → search_documents(query="tag:tagname")
├─ By type → search_documents(query="type:typename")
├─ By correspondent → search_documents(query="correspondent:name")
├─ By date → search_documents(query="created:[2024 to 2025]")
└─ Combined → search_documents(query="tag:X correspondent:Y created:[2024 to 2025]")
ドキュメントを整理する
What operation?
├─ Rename title → update_document(id=N, title="...")
├─ Set/clear ASN → update_document(id=N, archive_serial_number=N|null)
├─ Custom fields → update_document(id=N, custom_fields=[{field, value}]) (IDs via list_custom_fields)
├─ Add note → update_document(id=N, note="...")
├─ Remove note → delete_document_note(id=N, note_id=NID)
├─ Add tag → bulk_edit_documents(method="add_tag", tag=ID)
├─ Remove tag → bulk_edit_documents(method="remove_tag", tag=ID)
├─ Multi-tag → bulk_edit_documents(method="modify_tags", add_tags=[...], remove_tags=[...])
├─ Set type → bulk_edit_documents(method="set_document_type", document_type=ID)
├─ Set sender → bulk_edit_documents(method="set_correspondent", correspondent=ID)
├─ Merge PDFs → bulk_edit_documents(method="merge", metadata_document_id=ID)
├─ Rotate pages → bulk_edit_documents(method="rotate", degrees=90|180|270)
├─ Delete pages → bulk_edit_documents(method="delete_pages", pages=[1, 3, 5])
├─ Reprocess OCR → bulk_edit_documents(method="reprocess")
├─ Delete → bulk_edit_documents(method="delete") → goes to TRASH
├─ Undo a delete → list_trash → restore_from_trash(documents=[...])
└─ Purge for good → empty_trash(documents=[...]) !! PERMANENT !!
ドキュメントをアップロードする
1. Resolve metadata IDs first:
├─ list_tags → find or create_tag
├─ list_correspondents → find or create_correspondent
└─ list_document_types → find or create_document_type
2. post_document(file_path="~/Downloads/name.pdf", tags=[...], correspondent=ID, ...)
→ returns a task UUID, not a document ID
(file=<base64> + filename also works, but only for small files)
3. get_task(task_id=<uuid>) until status="SUCCESS"
→ related_document holds the new document ID
Lost the UUID? → list_tasks(task_name="consume_file") shows recent uploads;
list_tasks(status="FAILURE") shows rejected ones (e.g. duplicates)
タクソノミーを管理する（タグ／連絡先／種類）
Need to change metadata objects?
├─ View all → list_tags / list_correspondents / list_document_types /
│ list_storage_paths / list_custom_fields
│ (all take an optional name= substring filter)
├─ Resolve one ID → get_tag / get_correspondent / get_document_type
├─ Create new → create_tag / create_correspondent / create_document_type /
│ create_storage_path / create_custom_field
├─ Edit tag → update_tag(id, name, color, match, matching_algorithm)
├─ Edit sender → update_correspondent(id, name, match, matching_algorithm)
├─ Edit type → update_document_type(id, name, match, matching_algorithm)
├─ Edit storage path → update_storage_path(id, name, path, match, matching_algorithm)
├─ Edit custom field → update_custom_field(id, name, data_type, extra_data)
├─ Batch delete/perm → bulk_edit_tags / bulk_edit_correspondents /
│ bulk_edit_document_types / bulk_edit_storage_paths
└─ Del custom field → delete_custom_field(id) !! drops values from all docs !!
重要な注意事項
- search_documents は
content を除外します。トークンを節約するためです。OCR テキスト全体を取得するには、get_document を使用してください。
- post_document では
file_path が優先されます。MCP サーバーは自身のファイルシステムからファイルを読み取るため、サイズは問題になりません。インラインの base64（file + filename）はモデルを経由するため、小さいファイルにのみ使用してください。file_path が使えるのは stdio トランスポートのみです。HTTP トランスポートでは拒否されます。
- matching_algorithm は、すべてのエンドポイント（タグ、連絡先、文書タイプ）で整数
0-6 を指定します。0=なし、1=いずれか、2=すべて、3=完全一致、4=正規表現、5=あいまい一致、6=自動です。tools.md を参照してください。
- メールルールは今後の取り込みに適用されます。 create/update/delete_mail_rule によって、次回のメールポーリングで取り込まれる内容が変わります。すでに取り込み済みの文書には影響しません。削除する代わりに
enabled=false にして一時停止してください。メールアカウントの認証情報はレスポンスに表示されず、MCP 経由では設定できません（Web UI のみ）。
- 文書のバイナリは MCP リソースです。download_document で base64 を取得する代わりに、resources/read を使って
paperless://documents/{id}/archive|original|thumbnail を読み取ってください。download_document に as_resource_link=true を渡すと、リンクを取得できます。サムネイルは、ファイル全体を取得せずに確認できる低コストのプレビューです。
- 文書の削除は論理削除です。
bulk_edit_documents(method="delete") は文書をゴミ箱に移動します。保存期間が過ぎるか、empty_trash で完全削除されるまでは、restore_from_trash で復元できます。分類データ（タグ、連絡先、文書タイプ、保存先パス、カスタムフィールド）の削除は即時に反映され、元に戻せません。
- download_document は、base64 のデータと content-disposition から取得したファイル名を返します。
- list_tags、list_correspondents、list_document_types は、ページ分割された結果セット全体を返します。ID は
all の ID リストだけからではなく、results から使用してください。
- bulk_edit_documents はトップレベルの MCP フィールドを受け取りますが、Paperless には内部でネストされた
parameters オブジェクトが渡されます。MCP ツールは選択された method に関連するフィールドのみを転送します。
- update_document は単一の文書のみを対象とします（タイトル／ASN／カスタムフィールド／メモ）。バックエンドの一括エンドポイントには
set_title メソッドがないため、名前の変更には update_document を使用してください。タグ、連絡先、タイプには bulk_edit_documents を使用してください。note はメモを追加します（メモは内部的に Paperless の別エンドポイントに保存されます）。メモを削除するには delete_document_note を使用してください。
- メモは追記専用のログです。 1 つの文書に、各自のタイムスタンプと作成者を持つ複数のメモを保存できます。編集操作はありません。API にも Web UI にもありません。これはログの仕様による設計です。以前のメモを訂正するには、新しいメモを追加してください（例：「訂正：...」）。
delete_document_note は本当に削除が必要な項目にのみ使用してください。削除すると履歴が書き換わります。
- post_document が返すのは文書 ID ではなくタスク UUID です。
status="SUCCESS" になるまで get_task(task_id) をポーリングしてください。その後、related_document に作成された文書 ID が格納されます。
- カスタムフィールドの値には list_custom_fields から取得した ID が必要です。
update_document.custom_fields または bulk_edit_documents.modify_custom_fields を呼び出す前に、そこでフィールド名から数値 ID を特定してください。
- delete_tag は非推奨です（v3.0.0 で削除予定）。連絡先、文書タイプ、保存先パスと同様に、
operation="delete" を指定して bulk_edit_tags を使用してください。
- delete_custom_field は単一削除のみです。バックエンドにはカスタムフィールドの一括エンドポイントがありません。削除は取り消せず、そのフィールドを使用しているすべての文書から値が削除されます。
参考資料
