ペーパーレス-NGX MCP サーバー
Paperless-NGX APIサーバーと連携するためのMCP（モデルコンテキストプロトコル）サーバー。このサーバーは、Paperless-NGXインスタンス内のドキュメント、タグ、対応関係、ドキュメントタイプを管理するためのツールを提供します。
クイックスタート
Smithery経由でインストール
Smithery経由で Claude Desktop 用の Paperless NGX MCP Server を自動的にインストールするには:
npx -y @smithery/cli install @nloui/paperless-mcp --client claude
手動インストール
- MCP サーバーをインストールします。
npm install -g paperless-mcp
- これを Claude の MCP 構成に追加します。
VSCode 拡張機能の場合は、 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonを編集します。
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
}
}
}
Claude デスクトップ アプリの場合は、 ~/Library/Application Support/Claude/claude_desktop_config.jsonを編集します。
{
"mcpServers": {
"paperless": {
"command": "npx",
"args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
}
}
}
- API トークンを取得します:
- Paperless-NGXインスタンスにログインする
- 右上のユーザー名をクリックします
- 「マイプロフィール」を選択
- 新しいトークンを生成するには、円形の矢印ボタンをクリックします
- MCP 構成内のプレースホルダーを置き換えます。
http://your-paperless-instance:8000 Paperless-NGX の URL を入力）your-api-token先ほど生成したトークンに置き換えます
これで完了です。これで、Claude に Paperless-NGX ドキュメントの管理を依頼できるようになりました。
使用例
クロードに依頼できる作業は以下のとおりです。
- 「「請求書」のタグが付いたすべての文書を表示」
- 「『納税申告書』を含む文書を検索」
- 「#FF0000 の色で「領収書」という新しいタグを作成します」
- 「文書#123をダウンロード」
- 「すべての通信員をリストする」
- 「「銀行取引明細書」という新しい文書タイプを作成します」
利用可能なツール
ドキュメント操作
ドキュメント一覧
すべてのドキュメントのページ分けされたリストを取得します。
パラメータ:
- ページ（オプション）: ページ番号
- page_size (オプション): ページあたりのドキュメント数
list_documents({
page: 1,
page_size: 25
})
ドキュメントを取得する
ID で特定のドキュメントを取得します。
パラメータ:
get_document({
id: 123
})
検索文書
ドキュメント全体の全文検索。
パラメータ:
search_documents({
query: "invoice 2024"
})
ダウンロードドキュメント
ID でドキュメント ファイルをダウンロードします。
パラメータ:
- id: ドキュメントID
- オリジナル（オプション）：trueの場合、アーカイブ版ではなくオリジナルファイルをダウンロードします
download_document({
id: 123,
original: false
})
ドキュメントの一括編集
複数のドキュメントに対して一括操作を実行します。
パラメータ:
- documents: ドキュメントIDの配列
- 方法: 次のいずれか:
- set_correspondent: ドキュメントの通信相手を設定する
- set_document_type: ドキュメントのドキュメントタイプを設定する
- set_storage_path: ドキュメントの保存パスを設定する
- add_tag: ドキュメントにタグを追加する
- Remove_tag: ドキュメントからタグを削除します
- modify_tags: 複数のタグを追加または削除する
- 削除: ドキュメントを削除する
- 再処理: ドキュメントを再処理する
- set_permissions: ドキュメントの権限を設定する
- マージ: 複数のドキュメントを結合する
- 分割: 文書を複数の文書に分割する
- 回転: ドキュメントページを回転する
- delete_pages: ドキュメントから特定のページを削除する
- 方法に基づく追加パラメータ:
- 特派員: set_correspondent の ID
- document_type: set_document_typeのID
- storage_path: set_storage_pathのID
- タグ: add_tag/remove_tag の ID
- add_tags: modify_tagsのタグIDの配列
- Remove_tags: modify_tagsのタグIDの配列
- 権限: 所有者、権限、マージフラグを持つ set_permissions のオブジェクト
- metadata_document_id: メタデータソースを指定するためのマージID
- delete_originals: マージ/分割のブール値
- pages: 分割文字列 "[1,2-3,4,5-7]" または delete_pages "[2,3,4]"
- 度: 回転する数値（90、180、または270）
例:
// Add a tag to multiple documents
bulk_edit_documents({
documents: [1, 2, 3],
method: "add_tag",
tag: 5
})
// Set correspondent and document type
bulk_edit_documents({
documents: [4, 5],
method: "set_correspondent",
correspondent: 2
})
// Merge documents
bulk_edit_documents({
documents: [6, 7, 8],
method: "merge",
metadata_document_id: 6,
delete_originals: true
})
// Split document into parts
bulk_edit_documents({
documents: [9],
method: "split",
pages: "[1-2,3-4,5]"
})
// Modify multiple tags at once
bulk_edit_documents({
documents: [10, 11],
method: "modify_tags",
add_tags: [1, 2],
remove_tags: [3, 4]
})
投稿文書
Paperless-NGX に新しいドキュメントをアップロードします。
パラメータ:
- ファイル: Base64 でエンコードされたファイルの内容
- ファイル名: ファイル名
- タイトル（オプション）: ドキュメントのタイトル
- created (オプション): ドキュメントが作成された日時 (例: "2024-01-19" または "2024-01-19 06:15:00+02:00")
- 通信員（オプション）：通信員のID
- document_type (オプション): ドキュメントタイプのID
- storage_path (オプション): ストレージパスのID
- tags (オプション): タグIDの配列
- archive_serial_number (オプション): アーカイブのシリアル番号
- custom_fields (オプション): カスタムフィールドIDの配列
post_document({
file: "base64_encoded_content",
filename: "invoice.pdf",
title: "January Invoice",
created: "2024-01-19",
correspondent: 1,
document_type: 2,
tags: [1, 3],
archive_serial_number: "2024-001"
})
タグ操作
リストタグ
すべてのタグを取得します。
タグを作成する
新しいタグを作成します。
パラメータ:
- name: タグ名
- 色 (オプション): 16進カラーコード (例: "#ff0000")
- 一致（オプション）：一致するテキストパターン
- マッチングアルゴリズム（オプション）: 「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか
create_tag({
name: "Invoice",
color: "#ff0000",
match: "invoice",
matching_algorithm: "fuzzy"
})
特派員業務
特派員リスト
すべての特派員を取得します。
特派員を作成する
新しい特派員を作成します。
パラメータ:
- 名前: 通信者名
- 一致（オプション）：一致するテキストパターン
- マッチングアルゴリズム（オプション）: 「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか
create_correspondent({
name: "ACME Corp",
match: "ACME",
matching_algorithm: "fuzzy"
})
ドキュメントタイプの操作
ドキュメントタイプのリスト
すべてのドキュメント タイプを取得します。
ドキュメントタイプの作成
新しいドキュメント タイプを作成します。
パラメータ:
- name: ドキュメントタイプ名
- 一致（オプション）：一致するテキストパターン
- マッチングアルゴリズム（オプション）: 「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか
create_document_type({
name: "Invoice",
match: "invoice total amount due",
matching_algorithm: "any"
})
エラー処理
次の場合、サーバーは明確なエラー メッセージを表示します。
- Paperless-NGX URL または API トークンが正しくありません
- Paperless-NGXサーバーにアクセスできません
- 要求された操作は失敗しました
- 指定されたパラメータは無効です
発達
サーバーに貢献したり、修正したりしたいですか？必要な情報は次のとおりです。
- リポジトリをクローンする
- 依存関係をインストールします:
- server.jsに変更を加えます
- ローカルでテストする:
node server.js http://localhost:8000 your-test-token
サーバーは以下を使用して構築されています:
- litemcp : MCP サーバーを構築するための TypeScript フレームワーク
- zod : TypeScriptファーストのスキーマ検証
APIドキュメント
このMCPサーバーは、Paperless-NGX REST APIのエンドポイントを実装しています。基盤となるAPIの詳細については、公式ドキュメントをご覧ください。