ペーパーレス-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

手動インストール

1. MCP サーバーをインストールします。

npm install -g paperless-mcp

2. これを 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"]
    }
  }
}

3. API トークンを取得します:

   1. Paperless-NGXインスタンスにログインする

   2. 右上のユーザー名をクリックします

   3. 「マイプロフィール」を選択

   4. 新しいトークンを生成するには、円形の矢印ボタンをクリックします

4. MCP 構成内のプレースホルダーを置き換えます。

   • http://your-paperless-instance:8000 Paperless-NGX の URL を入力）

   • your-api-token先ほど生成したトークンに置き換えます

これで完了です。これで、Claude に Paperless-NGX ドキュメントの管理を依頼できるようになりました。

Related MCP server: mcp-paperless-ngx

使用例

クロードに依頼できる作業は以下のとおりです。

• 「「請求書」のタグが付いたすべての文書を表示」

• 「『納税申告書』を含む文書を検索」

• 「#FF0000 の色で「領収書」という新しいタグを作成します」

• 「文書#123をダウンロード」

• 「すべての通信員をリストする」

• 「「銀行取引明細書」という新しい文書タイプを作成します」

利用可能なツール

ドキュメント操作

ドキュメント一覧

すべてのドキュメントのページ分けされたリストを取得します。

パラメータ:

• ページ（オプション）: ページ番号

• page_size (オプション): ページあたりのドキュメント数

list_documents({
  page: 1,
  page_size: 25
})

ドキュメントを取得する

ID で特定のドキュメントを取得します。

パラメータ:

• id: ドキュメント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"
})

タグ操作

リストタグ

すべてのタグを取得します。

list_tags()

タグを作成する

新しいタグを作成します。

パラメータ:

• name: タグ名

• 色 (オプション): 16進カラーコード (例: "#ff0000")

• 一致（オプション）：一致するテキストパターン

• マッチングアルゴリズム（オプション）: 「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか

create_tag({
  name: "Invoice",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: "fuzzy"
})

特派員業務

特派員リスト

すべての特派員を取得します。

list_correspondents()

特派員を作成する

新しい特派員を作成します。

パラメータ:

• 名前: 通信者名

• 一致（オプション）：一致するテキストパターン

• マッチングアルゴリズム（オプション）: 「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか

create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: "fuzzy"
})

ドキュメントタイプの操作

ドキュメントタイプのリスト

すべてのドキュメント タイプを取得します。

list_document_types()

ドキュメントタイプの作成

新しいドキュメント タイプを作成します。

パラメータ:

• 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サーバーにアクセスできません

• 要求された操作は失敗しました

• 指定されたパラメータは無効です

発達

サーバーに貢献したり、修正したりしたいですか？必要な情報は次のとおりです。

1. リポジトリをクローンする

2. 依存関係をインストールします:

npm install

3. server.jsに変更を加えます

4. ローカルでテストする:

node server.js http://localhost:8000 your-test-token

サーバーは以下を使用して構築されています:

• litemcp : MCP サーバーを構築するための TypeScript フレームワーク

• zod : TypeScriptファーストのスキーマ検証

APIドキュメント

このMCPサーバーは、Paperless-NGX REST APIのエンドポイントを実装しています。基盤となるAPIの詳細については、公式ドキュメントをご覧ください。