Paperless-NGX MCP Server

Paperless-NGX MCP サーバー

Paperless-NGX API サーバーと連携するための MCP（Model Context Protocol）サーバーです。このサーバーは、Paperless-NGX インスタンス内のドキュメント、タグ、連絡先、ドキュメントの種類を管理するツールを提供します。

クイックスタート

インストール

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. 「My Profile」を選択します
   4. 円形の矢印ボタンをクリックして、新しいトークンを生成します

4. MCP 設定のプレースホルダーを置き換えます：

   • http://your-paperless-instance:8000 を Paperless-NGX の URL に置き換えます
   • your-api-token を、先ほど生成したトークンに置き換えます

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

使用例

Claude に次のような作業を依頼できます：

• 「『Invoice』タグが付いたドキュメントをすべて表示して」
• 「『tax return』を含むドキュメントを検索して」
• 「色を #FF0000 にして、『Receipts』という新しいタグを作成して」
• 「ドキュメント #123 をダウンロードして」
• 「連絡先をすべて一覧表示して」
• 「『Bank Statement』という新しいドキュメントの種類を作成して」

利用可能なツール

ドキュメント操作

list_documents

すべてのドキュメントのページ分割された一覧を取得します。

パラメーター：

• page（任意）：ページ番号
• page_size（任意）：1 ページあたりのドキュメント数

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

get_document

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

パラメーター：

• id：ドキュメント ID

get_document({
  id: 123
})

search_documents

ドキュメントを全文検索します。

パラメーター：

• query：検索クエリ文字列

search_documents({
  query: "invoice 2024"
})

download_document

ID を指定して、ドキュメントファイルをダウンロードします。

パラメーター：

• id：ドキュメント ID
• original（任意）：true の場合、アーカイブ版ではなく元のファイルをダウンロードします

download_document({
  id: 123,
  original: false
})

bulk_edit_documents

複数のドキュメントに対して一括操作を実行します。

パラメーター：

• documents：ドキュメント ID の配列
• method：以下のいずれか：
  • set_correspondent：ドキュメントの連絡先を設定します
  • set_document_type：ドキュメントの種類を設定します
  • set_storage_path：ドキュメントの保存先パスを設定します
  • add_tag：ドキュメントにタグを追加します
  • remove_tag：ドキュメントからタグを削除します
  • modify_tags：複数のタグを追加または削除します
  • delete：ドキュメントを削除します
  • reprocess：ドキュメントを再処理します
  • set_permissions：ドキュメントの権限を設定します
  • merge：複数のドキュメントを結合します
  • split：ドキュメントを複数に分割します
  • rotate：ドキュメントのページを回転します
  • delete_pages：ドキュメントから指定したページを削除します
• method に応じた追加パラメーター：
  • correspondent：set_correspondent 用の ID
  • document_type：set_document_type 用の ID
  • storage_path：set_storage_path 用の ID
  • tag：add_tag/remove_tag 用の ID
  • add_tags：modify_tags 用のタグ ID の配列
  • remove_tags：modify_tags 用のタグ ID の配列
  • permissions：owner、permissions、merge フラグを含む set_permissions 用のオブジェクト
  • metadata_document_id：メタデータの取得元を指定する merge 用の ID
  • delete_originals：merge/split 用のブール値
  • pages：split 用の文字列 "[1,2-3,4,5-7]"、または delete_pages 用の "[2,3,4]"
  • degrees：rotate 用の数値（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]
})

post_document

新しいドキュメントを Paperless-NGX にアップロードします。

パラメーター：

• file：Base64 エンコードされたファイルの内容
• filename：ファイル名
• title（任意）：ドキュメントのタイトル
• created（任意）：ドキュメントが作成された日時（例："2024-01-19" または "2024-01-19 06:15:00+02:00"）
• correspondent（任意）：連絡先の 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

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

list_tags()

create_tag

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

パラメーター：

• name：タグ名
• color（任意）：16進数のカラーコード（例：「#ff0000」）
• match（任意）：照合するテキストパターン
• matching_algorithm（任意）：「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか

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

コレスポンデント操作

list_correspondents

すべてのコレスポンデントを取得します。

list_correspondents()

create_correspondent

新しいコレスポンデントを作成します。

パラメーター：

• name：コレスポンデント名
• match（任意）：照合するテキストパターン
• matching_algorithm（任意）：「any」、「all」、「exact」、「regular expression」、「fuzzy」のいずれか

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

ドキュメントタイプ操作

list_document_types

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

list_document_types()

create_document_type

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

パラメーター：

• name：ドキュメントタイプ名
• match（任意）：照合するテキストパターン
• matching_algorithm（任意）：「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 の詳細については、公式ドキュメントを参照してください。

MCP サーバーの実行

MCP サーバーは 2 つのモードで実行できます：

1. stdio（デフォルト）

これがデフォルトのモードです。サーバーは stdio 経由で通信するため、CLI や直接統合に適しています。

npm run start -- <baseUrl> <token>

2. HTTP（Streamable HTTP Transport）

サーバーを HTTP サービスとして実行するには、--http フラグを使用します。--port でポートを指定することもできます（デフォルト：3000）。このモードでは Express のインストールが必要です（依存関係に含まれています）。

npm run start -- <baseUrl> <token> --http --port 3000

• MCP API は、指定したポートの POST /mcp で利用できます。
• 各リクエストは、StreamableHTTPServerTransport のパターンに従って、ステートレスに処理されます。
• /mcp への GET および DELETE リクエストは 405 Method Not Allowed を返します。