Paperless-ngx

mcp-paperless-ngx

Model Context Protocol に対応する Paperless-ngx 3.x 用サーバー
REST API を全面的にカバーし、スキーマを考慮した、トークン効率の高い設計です。

---

REST API バージョン 10 に対応し、次の 3 点で他とは異なる設計になっています。

• 網羅状況を明示。 ドキュメントに記載されている 92 個すべてのエンドポイントを、ツールとして公開するか、除外する理由を明記したうえで src/tools/coverage.ts に一覧表示しています。これをテストで検証するため、Paperless のリリースでエンドポイントが追加されると、サポートされないまま見過ごされるのではなく、CI が失敗します。
• トークンを節約。 Paperless のドキュメントには OCR の全文が含まれます。単純なラッパーはデフォルトでこれを返すため、検索を 1 回行っただけでモデルのコンテキストを使い切ることがあります。このサーバーでは、リスト結果を ?fields= によってサーバー側で絞り込み、本文は専用のページネーション対応ツールから取得します。また、リストエンドポイントが生の API レスポンスをそのまま返すことはありません。これもテストで検証されます。コンテキストコストを参照してください。
• 機能を絞ったインターフェース。 99 個ものツールをモデルのツール一覧に並べると、使い勝手が損なわれます。ツールセットを使えば、各クライアントに必要な機能だけを公開でき、--read-only を指定すると書き込み経路を完全に無効化できます。

Paperless-ngx 2.x はサポート対象外です。API バージョン 10 で追加されたエンドポイント（ネストされたタグ、ドキュメントのバージョン、share_link_bundles、分割された PDF 操作）が存在することを前提としているためです。

クイックスタート

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://paperless.example.com \
  --env PAPERLESS_TOKEN=your-api-token \
  -- npx -y mcp-paperless-ngx

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

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "mcp-paperless-ngx"],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "your-api-token"
      }
    }
  }
}

API トークンの取得

Paperless のウェブ UI → ユーザー名（右上）→ マイプロフィール → API トークン欄の横にある円形の矢印ボタン。

設定

変数	必須	デフォルト	用途
PAPERLESS_URL	はい	—	サーバーが接続するベース URL です。
PAPERLESS_TOKEN	はい	—	API トークンです。PAPERLESS_API_KEY も使用できます。
PAPERLESS_PUBLIC_URL	いいえ	PAPERLESS_URL	外部から別の名前でインスタンスにアクセスする場合に、ユーザー向けリンクの生成に使用する URL です。
PAPERLESS_TOOLSETS	いいえ	下記参照	カンマ区切りのツールセット、または all を指定します。
PAPERLESS_READ_ONLY	いいえ	false	変更を行わないツールのみを公開します。
PAPERLESS_HEADERS	いいえ	—	JSON（{"X-Auth":"…"}）または Name: value, Name: value 形式の追加リクエストヘッダーです。Authentik や Authelia などのフォワード認証プロキシの背後で必要です。
PAPERLESS_DOWNLOAD_DIR	いいえ	システムの一時ディレクトリ	ダウンロードしたファイルの保存先です。
PAPERLESS_MAX_PAGE_SIZE	いいえ	100	モデルの指定にかかわらず適用される、リストのページサイズ上限です。
PAPERLESS_TIMEOUT_MS	いいえ	60000	リクエストのタイムアウトです。
PAPERLESS_API_VERSION	いいえ	10	Accept ヘッダーで送信する REST API のバージョンです。

CLI フラグ --url、--token、--public-url、--toolsets、--read-only は環境変数より優先されます。--check は接続を確認し、--list-tools は有効なツールを出力します。

ツールセット

ツールセット	デフォルト	内容
documents	on	検索、読み取り、更新、削除、アップロード、ダウンロード、メモ、一括操作、PDF 操作
metadata	on	タグ、連絡先、ドキュメントの種類、保存先パス
customfields	on	カスタムフィールドの定義
views	on	保存済みビュー
sharing	on	共有リンクと共有リンクバンドル
workflows	on	自動化ルール、トリガー、アクション
system	on	全体検索、統計、ステータス、タスク、ゴミ箱
mail	off	IMAP アカウント、メールルール、処理済みメール
admin	off	ユーザー、グループ、プロフィール、設定、ログ（読み取り専用）

ほとんどのセッションで必要になることはなく、ツールを追加するたびにリクエストごとのコンテキストコストが増えるため、mail と admin はデフォルトでオフになっています。明示的に有効にしてください。

PAPERLESS_TOOLSETS=documents,metadata,system,mail
PAPERLESS_TOOLSETS=all

コンテキストコスト

API を言語モデル向けにラップすると、API 自体にはないコストが発生します。モデルが目にするものはすべて、リクエストのたびにコストがかかります。特に影響が大きい 2 つの箇所と、このサーバーでの対処方法を紹介します。

レスポンス。 Paperless では、次の 3 種類のレスポンスはコストが高く、意図せず返してしまいがちです。

ソース	問題	対処
ドキュメント一覧	すべてのドキュメントに、完全な OCR テキストが content として含まれます	?fields= でサーバー側のレスポンスを制限します。get_document_content ではテキストを別途ページ分割して返します
/api/search/	すべてのオブジェクトタイプにわたり、OCR テキストを含む水和済みの Document オブジェクトを返します	ドキュメントは要約し、その他のタイプは id + name に縮約します
ワークフロー、メールルール、グループ、タスク	オブジェクトごとに 27～34 個のフィールドがあり、ネストされたトリガー／アクション定義もインラインで含まれます	識別に必要なフィールドだけに要約し、ネストされたリストは件数に縮約します。full: true を指定するとすべて返します

ツール定義。 こちらのほうがコストが大きく、見落とされがちです。ツール名、説明、JSON スキーマは、ツールを呼び出すかどうかにかかわらず、すべてのリクエストに含まれます。

ツールセット	ツール数	リクエストあたりのおおよそのコスト
all	99	約 20,500 トークン
default	85	約 18,500 トークン
documents,metadata	49	約 12,900 トークン

このコストをなくす方法はありません。モデルが推測せずに使えるツールの対価です。 ただし、意識して選ぶ価値はあります。セッションで行うのがドキュメントの検索と整理だけなら、PAPERLESS_TOOLSETS=documents,metadata を設定することで、レスポンスをどれだけ削減するよりも多くのコンテキストを節約できます。

安全性

このサーバーは破壊的操作を公開しています。それらがなければドキュメント管理ツールとして十分に機能しないためです。適切な操作かどうかを推測することはしません。その判断はクライアントとユーザーに委ねられます。代わりに、次の対策を行っています。

• 破壊的操作を行うツールには destructiveHint: true の注釈を付け、MCP クライアントが確認を必須にできるようにしています。
• ツールの説明では、元に戻せない操作（empty_trash、delete_custom_field、delete_originals）を明記し、呼び出す前に確認するよう求めています。
• --read-only を指定すると、書き込みツールは呼び出し時に拒否されるのではなく、すべて一覧から除外されます。
• 一括操作のエンドポイントでは、フィルターに一致するすべての項目に適用するモードをサポートしています。このサーバーでは公開していません。一括操作ツールは明示的な ID リストを受け取るため、誤ったフィルターによってアーカイブ全体に気付かないまま影響が及ぶことはありません。
• create_share_link は誰でもアクセスできる URL を生成します。その説明で明記しており、すでに公開されている内容を確認するために audit_sharing プロンプトを用意しています。

認証情報に関連するエンドポイント（トークンの生成、TOTP の登録、他人の第 2 要素認証の無効化）は、意図的に公開していません。一覧とその理由については、EXCLUDED_ENDPOINTS を参照してください。

プロンプト

MCP プロンプトをサポートするクライアントでは、スラッシュコマンドとして登録されます。

プロンプト	内容
triage_inbox	未仕分けのドキュメントを確認し、既存のエントリーを優先してメタデータを提案します。ユーザーが承認するまで何も適用しません。
find_document	曖昧な説明からドキュメントを探します。まず低コストの検索を行い、その後、検索範囲を広げます。
audit_sharing	すべての公開共有リンクを確認し、有効期限のないリンクにフラグを付けます。

テスト

異なる点を確認するため、3 つのレイヤーがあります。

npm test                                        # logic — no network
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/smoke-test.mjs                   # all 55 read-only tools, live
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/write-test.mjs                   # writes, live — see the warning

npm test は、このサーバー自体の処理を確認します。エンドポイントの網羅状況、スキーマに対する列挙値の一致、一覧取得ツールが未加工の API オブジェクトを漏らさないこと、読み取り専用モードで書き込み機能が実際に削除されることを検証します。

smoke-test.mjs は、Paperless に関する前提を確認します。実際のインスタンスに対してすべての読み取り専用ツールを呼び出し、ID をハードコードせずに一覧取得の結果から解決し、応答サイズを表示して、コストの高いツールを把握できるようにします。何も書き込みません。

write-test.mjs は、それ以外を網羅します。アップロードと消費、あらゆるフィールド型の更新、メモ、一括タグ編集、共有リンク、回転、ゴミ箱への移動と復元を確認します。

このテストが操作するのは、テスト自身が作成したオブジェクトだけです。 作成するものにはすべて zz-mcp-test のプレフィックスを付け、最後に削除します。また、自分がアップロードしていないドキュメントを 変更することもありません。実行が中断された場合は、このプレフィックスが付いた残りのオブジェクトを安全に削除できます。 お持ちであれば、テスト用インスタンスを使うことをおすすめします。

Paperless の変更への対応

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs
npm test

sync-schema.mjs は、独自のインスタンスの OpenAPI ドキュメントから schema/endpoints.json を再生成します。 その後、テストスイートが、公開も明示的な除外もされていないエンドポイントを報告します。これがメンテナンスのすべてです。より新しい Paperless を指定すれば、変更点をテストが教えてくれます。

開発

npm install
npm start          # run from source
npm run build      # compile to build/
npm test           # unit tests + coverage checks
npm run inspect    # build, then open the MCP inspector

先行事例

Paperless-ngx 向けの MCP サーバーはいくつかあり、特に活発な 2 つはいずれも 3.x に対応しています。 cubinet-code/paperless-ngx-mcp は 2.x と 3.x の違いを自動で吸収し、baruchiro/paperless-mcp では API バージョン（PAPERLESS_API_VERSION、デフォルトは 9）を選べます。1 つのインストールで両方のメジャーバージョンに対応する必要がある場合は、どちらかをお使いください。

このサーバーは、逆の方針を取っています。API バージョン 10 のみを前提とし、それ以前のバージョンには対応しません。これにより、3.x で導入されたエンドポイント（ネストされたタグ、ドキュメントのバージョン、share_link_bundles、独立した PDF 操作）を利用でき、文書化された 92 個すべてのエンドポイントが網羅されていることをテストで確認できます。また、サーバー側で ?fields= を使って一覧の応答を絞り込むため、デフォルトでは OCR テキストも含まれません。

ライセンス

MIT。LICENSE をご覧ください。

---

_{eichner.cloud が開発 — セルフホスト可能で、かなり気に入っています。}