Paperless MCP

Paperless MCP

MCP 経由で Paperless-NGX を操作：ドキュメントの検索、閲覧、アップロード、タグ付けに加え、取引先や種類を管理できます。

ドキュメント | 設定ウィザード | PyPI | Docker

機能

• ファイル転送リンク： HTTP 経由でドキュメントファイルと OCR 全文の Markdown をダウンロードできます。同じ転送ルートを使って、Markdown を含むファイルをアップロードできます。ツールを有効にするには PAPERLESS_MCP_BASE_URL を設定します。ファイルのバイトデータはモデルのコンテキスト外に保持されます。ファイル転送リンクを参照してください。
• ドキュメントの検索と取得： Paperless-NGX に対する全文検索およびフィルター付きリストクエリに加え、抽出された OCR テキスト、メタデータ、サムネイルにアクセスできます。
• タグ、取引先、ドキュメントの種類、カスタムフィールドの管理： Paperless が提供するすべての分類項目について、完全な CRUD と一括編集に対応します。
• ドキュメントのライフサイクル： アップロード、フィールドの変更、メモ、監査履歴、AI が提案するタグ・取引先・種類に対応します。
• 運用状況の確認： 保存済みビュー、ストレージパス、共有リンク、バックグラウンドタスク（wait_for_task を使用）、統計情報、Paperless-NGX の上流リリース確認に対応します。
• MCP ツール： Lucide アイコン付きの、LLM から参照できるツールが 49 個あります。src/paperless_mcp/tools/ を参照してください。
• MCP リソース： ドキュメントの範囲を限定したプレビューとドメインコレクションを公開する URI が 16 個あります。src/paperless_mcp/resources/ を参照してください。

できること

このサーバーを MCP クライアント（Claude など）に接続すると、次のことができます。

• 「ACME の前四半期の請求書を探してください。」 差出人フィルターを指定して search_documents を実行し、続いて get_document_content で範囲を限定したプレビューを読み取ります。
• 「この3つの文書に『確認済み』のタグを付け、差出人を「Accounting」に変更してください。」 bulk_edit_documents を1回の呼び出しで使用します。
• 「この PDF をアップロードして、OCR が終わるまで待ってください。」 upload_document と wait_for_task を組み合わせ、文書のインデックス作成が完了してからアシスタントが結果を報告するようにします。
• 「過去1週間で文書4213にどのような変更がありましたか？」 paperless://documents/4213/history を読み取り、監査履歴を要約します。

すべてのツールとリソースは、ドキュメントサイトの ツール と リソース に記載されています。サーバーが読み取る Paperless の変数については、設定 をご覧ください。

インストール

PyPI から

pip install pvliesdonk-paperless-mcp

pyproject.toml の PROJECT-EXTRAS-START / PROJECT-EXTRAS-END センチネルを使ってオプションの追加機能を追加した場合は、以下に記載してください。

• pip install pvliesdonk-paperless-mcp[docs]：ドキュメントサイトをローカルでビルドするための mkdocs-material と mkdocstrings[python] をインストールします（uv run mkdocs serve）。

ソースから

git clone https://github.com/pvliesdonk/paperless-mcp.git
cd paperless-mcp
uv sync --all-extras --all-groups

Docker

docker pull ghcr.io/pvliesdonk/paperless-mcp:latest

最新リリースではなく、マージされた最新のコードを実行するには、ローリング edge タグを使用してください。これは main へのマージごとに再ビルドされ、バージョン識別子を持ちません。すべてのタグについては、イメージタグ をご覧ください。

docker pull ghcr.io/pvliesdonk/paperless-mcp:edge

リポジトリのルートには compose.yml が含まれており、そのまま実行できます。.env.example を .env にコピーしてから、docker compose up -d を実行してください。ホスト上でポート8000を公開し、リバースプロキシがないことを前提としています。設定の分割、ドメインセンチネルブロック、Traefik オーバーレイについては、Docker Compose をご覧ください。

リモートの Python デバッガーを接続する方法（開発専用。このプロトコルは認証されません）については、リモートデバッグ をご覧ください。

Linux パッケージ（.deb / .rpm）

GitHub Releases ページから .deb または .rpm パッケージをダウンロードしてください。どちらもセキュリティ強化済みの systemd ユニットをインストールします。環境設定は /etc/paperless-mcp/env から読み込まれます（同梱の /etc/paperless-mcp/env.example をコピーしてください）。

Claude Desktop（.mcpb バンドル）

GitHub Releases ページから .mcpb バンドルをダウンロードしてダブルクリックでインストールするか、次のコマンドを実行してください。

mcpb install paperless-mcp-<version>.mcpb

Claude Desktop は GUI ウィザードを使って必須の環境変数を要求するため、JSON を手動で編集する必要はありません。

Claude Desktop の手動設定とセットアップのオプションについては、Claude Desktop のデプロイ をご覧ください。

リリースチャンネル

成果物は3つのチャンネルで配布されます。各行には、そのチャンネルで公開されるものをすべて記載しています。

チャンネル	バージョンの識別子	成果物
edge（ローリング）	なし。コミットが識別子になります	main へのマージごとに再ビルドされる Docker イメージ :edge、mcpb-bundle-edge ワークフロー成果物としての .mcpb バンドル、plugin-zip-edge 成果物としての Claude Code プラグイン .zip、ローリング unstable ドキュメントバージョン。git タグ、GitHub リリース、PyPI エントリは残りません。
プレリリース	リリースプルリクエスト内で算出・レビューされる vX.Y.Z-rc.N	PyPI（プレリリース X.Y.ZrcN として）、ホイール、sdist、.deb／.rpm パッケージ、.mcpb バンドル、プラグイン .zip、SBOM を添付した GitHub リリース、不変の vX.Y.Z-rc.N タグと並び順を考慮したローリング rc タグで公開される Docker イメージ。プラグインマーケットプレイス、MCP レジストリ、ドキュメントのデプロイは対象外です。
安定版	vX.Y.Z	すべて：PyPI、Docker（バージョンタグと、並び順を考慮した latest／vX／vX.Y）、.deb／.rpm、GitHub リリースアセット（ホイール、sdist、.mcpb バンドル、プラグイン .zip、SBOM）、プラグインマーケットプレイスと MCP レジストリのエントリ（そのリリースが最新の安定版の場合）、並び順を考慮した latest エイリアス付きのバージョン別ドキュメント。

候補版の .mcpb バンドルをインストールできるよう、プレリリースも PyPI に公開されます。このバンドルはコードを内包せず、PyPI を参照します。PEP 440 リゾルバーは、要件でプレリリースを指定するか --pre を渡さない限りプレリリースをスキップするため、通常のインストーラーには表示されません。pip install pvliesdonk-paperless-mcp==X.Y.ZrcN を実行して、名前で候補版を指定してください。PyPI では PEP 440 の正規形式で表記され、タグでは SemVer が使われます。ローリングポインターは並び順を考慮するため、古い release/X.Y ブランチから切ったパッチリリースによって latest 系のタグが古いコンテンツに戻ることはなく、すでにリリース済みのバージョンの候補版によって rc が動くこともありません。全体像については、リリースプロセスを参照してください。

クイックスタート

paperless-mcp serve                                # stdio transport
paperless-mcp serve --transport http --port 8000   # streamable HTTP

MCP トランスポートを介さずにドメインロジックを組み込んでライブラリとして使用する場合は、paperless_mcp パッケージから直接インポートしてください。エントリーポイントについては、src/paperless_mcp/ 配下にあるプロジェクトのドメインモジュールを参照してください。

サーバー情報

サーバーは組み込みの get_server_info ツール（fastmcp_pvl_core.register_server_info_tool 経由）を登録します。これにより、オペレーターは単一の MCP 呼び出しでデプロイ済みのバージョンを確認できます。デフォルトの応答には server_name、server_version、core_version が含まれます。リモート上流と通信するサーバーでは、src/paperless_mcp/server.py の DOMAIN-UPSTREAM-START／DOMAIN-UPSTREAM-END センチネル内で上流のバージョン報告を組み込みます。組み込み方法については、tool-registrationを参照してください。

ヘルスチェック

サーバーは MCP マウント外かつ認証外で、fastmcp_pvl_core.register_health_routes を介して /health（稼働状態、静的な 200）と /health/ready（バックエンドストアまたはドメインチェックに失敗した場合は 503 となる準備状態）を提供します。compose.yml は最初のルートをプローブします。ドメインの準備状態チェックは、src/paperless_mcp/server.py の health_checks 辞書に追加してください。ルート、マウントパスのルール、PAPERLESS_MCP_HEALTH_DETAIL については、Docker デプロイを参照してください。

設定

fastmcp-pvl-core ベースのすべてのサービスで共通して使用される、最も一般的な環境変数です。

変数	デフォルト	説明
PAPERLESS_MCP_KV_STORE_URL	file:///data/state	状態を必要とするすべての pvl-core サブシステムで共有される永続状態バックエンドの URL です。memory:// はプロセス内でのみ有効で、再起動すると失われます。file:///path は単一サーバー上に永続化されます。redis://、dynamodb://、mongodb:// では、それぞれ対応する追加機能が必要です。未設定の場合は、デフォルトで file:///data/state（Docker イメージの volume ファミリーがマウントするパス）になります。このディレクトリを使用できないホストでは、警告とともに memory:// になります。
PAPERLESS_MCP_LOG_LEVEL	INFO	FastMCP を含む、プロセス内のすべてのロガーのログレベルです（DEBUG / INFO / WARNING / ERROR / CRITICAL）。-v CLI フラグを指定すると、DEBUG に上書きされます。接頭辞のない FASTMCP_LOG_LEVEL もメジャーバージョン 1 つ分は引き続き使用できますが、非推奨の警告がログに記録されます。
PAPERLESS_MCP_LOG_FORMAT	（なし）	ログの出力形式です。rich はターミナル向けの、レコードごとに 1 行で色付きの event key=value を出力します。json はコレクター向けの、レコードごとに 1 つの JSON オブジェクトを出力します。未設定の場合、stderr がターミナルなら rich、それ以外なら json が選択されるため、コンテナーや journald では設定なしで JSON が出力されます。

この表とドメイン設定の表は、厳選した項目のみを掲載しています。サーバーが読み取るすべての変数を含む完全な自動生成リファレンスは、設定リファレンスをご覧ください。.env.example には、同じ内容がコピーして貼り付けられる形式で記載されています。

認証

呼び出し元は、ベアラートークンまたは OIDC（併用不可）で認証します。設定方法、複数サブジェクトに対応するトークン、OIDC、トラブルシューティングについては、認証ガイドをご覧ください。

スキャフォールド後のチェックリスト

copier copy と gh repo create --push の実行後：

1. README と AGENTS.md の DOMAIN ブロックをすべて埋めます（DOMAIN センチネルコメントが付いた各セクション）。GENERATED-ENV-TABLE-* 領域は DOMAIN ブロックではありません。設定ジェネレーターが管理しており、実行のたびに書き換えられます。
2. GitHub シークレットを設定します（以下を参照）。
3. 開発用とドキュメント用のツールをインストールします：uv sync --all-extras --all-groups。
4. pre-commit フックをインストールします：uv run pre-commit install。
5. ゲートをローカルで実行します：uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/。
6. 最初のコミットをプッシュします。CI が成功するはずです。

GitHub シークレット

CI ワークフローでは、必須のリポジトリシークレットを 2 つと、任意の Claude トークンを 1 つ参照します。Settings → Secrets and variables → Actions から、または gh secret set を使って設定してください。

シークレット	使用先	生成方法
RELEASE_TOKEN	release-prepare.yml、release.yml、copier-update.yml、renovate.yml、bootstrap.yml	https://github.com/settings/personal-access-tokens/new で、contents: write、pull_requests: write、administration: write を付与したきめ細かな PAT を作成します（bootstrap はリポジトリのルールセット、自動マージ、セキュリティ設定、About ブロックを適用します）。リポジトリ管理者のアカウントに属している必要があります。付属のルールセットでは管理者ロールにバイパス権限を付与しており、リリースプルリクエストのマージ後に knope が作成するリリースタグと GitHub リリースでも、この権限が必要です（トークンが作成するプルリクエストでも CI を実行するために必要です）。このリポジトリのみにスコープを限定してください。
SONAR_TOKEN	ci.yml	https://sonarcloud.io：リポジトリをインポートした後、その Administration → Analysis Method ページを開きます。SonarQube Cloud は Automatic Analysis が有効な状態では CI スキャンを拒否するため、まずここで Automatic Analysis をオフにしてください。GitHub Actions を選択すると、トークンが表示されます。このシークレットが設定されるまで、CI はスキャンをスキップします。
CLAUDE_CODE_OAUTH_TOKEN	claude.yml	任意です。ローカルで claude setup-token を実行し、@claude またはオプトインした自動レビューを使う場合にのみ設定してください。

gh secret set RELEASE_TOKEN
gh secret set SONAR_TOKEN
# Optional: enables @claude and opted-in automatic review.
gh secret set CLAUDE_CODE_OAUTH_TOKEN

依存関係の更新は Renovate（renovate.yml）が処理し、 RELEASE_TOKEN を再利用します。uv.lock を維持し、CI Success チェックが 成功するとパッチ／マイナーの更新を自動マージします。bootstrap.yml は 自動マージを有効にし、リポジトリのルールセット（.github/rulesets/）を適用し、 非公開の脆弱性レポートと Dependabot アラートを有効にして、初回の push 時に pyproject.toml からリポジトリの About ブロック（説明、Web サイト、 トピック）を設定します。ブランチごとの保護設定、バイパスモデル、 セキュリティ設定については、 リポジトリの保護を参照してください。GitHub Actions は copier テンプレートで更新され、リポジトリごとではなく copier update で反映されます。

GITHUB_TOKEN は自動的に提供されるため、操作は不要です。

ローカル開発

PR ゲート（CI と同じです）：

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

Pre-commit は各コミットでゲートの一部を実行します。詳細は .pre-commit-config.yaml を、Hard PR Acceptance Gates の全体については AGENTS.md を参照してください。

CI では、Python 3.11 から 3.14 までの各バージョンでテストが成功する必要があります。Python 3.14 ではブランチカバレッジも収集し、全体およびパッチのカバレッジしきい値 80% を適用します。 このテストコマンドを再現するには、 uv run --python 3.14 pytest --cov --cov-report=xml --durations=20 を実行してください。

トラブルシューティング

scaffold したプロジェクトの移動

uv sync は、venv の Python を指す絶対パスの shebang を持つ .venv/bin/* スクリプトを作成します。scaffold 後にリポジトリを移動すると（mv /old/path /new/path）、古い shebang が venv の site-packages とは異なるインタープリターを参照するため、uv run pytest は ModuleNotFoundError: No module named 'fastmcp' で失敗します。

修正方法：

rm -rf .venv
uv sync --all-extras --all-groups

uv run python -m pytest も、一時的な回避策として使えます（古いエントリースクリプトの shim を介さずに実行します）。

copier update 後の uv.lock の更新

copier update によって新しい依存関係（pyproject.toml.jinja に追加された新しい extra など）が導入されると、CI のインストール手順で uv sync --locked が実行され、古いロックファイルに対して失敗します。ローカルで uv lock を実行し、copier-update PR を受け入れる際に、更新した uv.lock もコミットしてください。

CI では --locked を使ってインストールし（レビューのワークフローでは --frozen）、ジョブが自身のワークスペースで uv.lock を書き換えることはありません。再ロックするジョブは、修正したばかりのずれを隠してしまい、ワークスペースが変更されると同じジョブ内で後続の git checkout が失敗するためです。ロックファイルのずれは、ひそかな変更ではなく、明確なメッセージとともにインストール手順が失敗して示されます。

コントリビューション

CONTRIBUTING.mdには、課題とプルリクエストのルール、および修正を加える場所が記載されています。ライブラリコードはfastmcp-pvl-core、テンプレートが管理するファイルはテンプレート、このリポジトリ内のDOMAIN-*／CONFIG-*／PROJECT-*ブロックに含まれるものはこのリポジトリが対象です。AGENTS.mdには規約とゲートが記載されています。.agents/skills/以下のスキルには、各タスクの手順が記載されています。これには、プルリクエスト前にローカルで自己レビューするself-reviewing、リリースノートの作成に関するwriting-release-notes、週次のテンプレート更新プルリクエストに関するapplying-template-updates、課題やプルリクエストの起票に関するauthoring-issues-prsが含まれます。リリース手順は[docs/deployment/release-process.md](docs/deployment/release-process.md)に、テンプレート更新手順は[docs/deployment/template-updates.md](docs/deployment/template-updates.md)に記載されています。脆弱性を非公開で報告する方法と、その後の流れについてはSECURITY.md`を参照してください。

リンク

• ドキュメント
• llms.txt
• FastMCP
• fastmcp-pvl-core

ドメイン設定

このプロジェクトがエントリーポイントとして使用する変数です（ドメイン変数にはPAPERLESS_MCP_プレフィックスが付きます）。

変数	デフォルト	必須	説明
PAPERLESS_MCP_PAPERLESS_URL	(none)	はい	Paperless-NGX REST APIのベースURLです。末尾にスラッシュを付けないでください。
PAPERLESS_MCP_API_TOKEN	(none)	はい	APIリクエストの送信に使用するPaperlessサービスアカウントのトークンです。
PAPERLESS_MCP_PAPERLESS_PUBLIC_URL	(none)	いいえ	ユーザーに表示するリンクに使用するPaperlessの公開UI URLです。デフォルトはPAPERLESS_URLです。

この一覧は厳選された項目です。tagsメタデータにreadmeが含まれるフィールドがここに表示されます。すべてのドメイン変数は設定リファレンスに記載されており、設定ウィザードと同じグループ分けになっています。

ドメイン設定のフィールドは、src/paperless_mcp/config.py内のCONFIG-FIELDS-START／CONFIG-FIELDS-ENDセンチネルの間に定義します。環境変数の読み取りにはfastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default)を使用し、命名規則を一貫させてください。また、フィールドの不変条件はCONFIG-VALIDATE-START／CONFIG-VALIDATE-ENDセンチネルの間にある__post_init__に記述してください。各フィールドのmetadataにあるhelp、tags、wizardグループから、リファレンスの表が直接生成されるため、内容を正確かつ完全に保ってください。

主な設計上の決定事項

• 読み取り専用のデプロイでは、ドメインの切り替えではなくツールの表示設定を使います。 PAPERLESS_MCP_TOOLS_DENY（または PAPERLESS_MCP_TOOLS_ALLOW）を設定すると、転送が有効な場合の create_upload_link を含む、変更を加えるツールを非表示にできます。このテンプレートでは make_server で最後に表示設定を適用するため、非表示のツールは tools/list から除外され、tools/call での呼び出しも拒否されます。クライアントは拒否される書き込みを呼び出せず、このルールはこのテンプレートを使って構築されるすべてのサーバーで一元管理されます。
• HTTP レイヤーが再試行するのは、冪等な読み取りのみです。 PAPERLESS_MCP_HTTP_RETRIES は、5xx エラーまたはネットワークエラーが発生した GET リクエストに適用されます。一括編集やアップロードが二重に適用されるのを防ぐため、書き込みが自動的に再試行されることはありません。
• ツールアイコンには Lucide を使います。 すべてのツールに Lucide アイコンのヒントを設定しているため、アイコンを表示する MCP クライアント（Claude Desktop）で統一感のある見た目になります。src/paperless_mcp/tools/_icons.py を参照してください。
• Paperless API との互換性： リクエストではバージョン 10 のペイロードを優先し、バージョンが明示的に拒否された場合は Paperless 2.x 向けにバージョン 9 へ自動的にフォールバックします。タスクには構造化された結果と所要時間のデータが含まれますが、従来のフィールドも維持されます。保存済みビューの表示フラグには null を指定できるようになりました。Python の利用者はこの値を処理する必要があります。タスクツールを参照してください。
• モデルは上流からの未知のフィールドを受け入れます。 Pydantic モデルでは、リストエンドポイントのレスポンスに対して緩やかな検証を行うため、新しい Paperless-NGX バージョンがクライアントの動作を妨げることはありません（Document.some_future_paperless_field テストでこの動作を確認します）。
• v1 にはプロンプトを含めません。 prompts.py は意図的に空にしてあります。プロンプトは、実際の利用を通じて具体的なユーザーワークフローのパターンが明らかになった段階で追加します。