laserfiche-mcp

laserfiche-mcp

セブンスデー・アドベンチスト教会総会が所有しています。Laserfiche とは提携しておらず、Laserfiche による推奨を受けていません。

Claude（Desktop、Code、または任意のMCP クライアント）を使って、セルフホストの Laserfiche リポジトリ内のドキュメントを検索・閲覧できます。オプトインすれば、 ドキュメントを変更することもできます。同じプログラムは、AI をまったく必要としない作業向けのコマンドラインツール（ls、cat、 search、dedupe など）としても利用できます。

デフォルトでは読み取り専用です。 LF_READ_ONLY=false を設定するまで書き込みは無効で、破壊的な操作には必ず2段階目の確認が必要です。 現在のリリース：v2.6.2 — 変更履歴をご覧ください。

クイックスタート

uv tool install laserfiche-mcp   # or run ad hoc: uvx laserfiche-mcp
laserfiche-mcp setup             # asks for your server + account, then tests the connection
laserfiche-mcp ls 1              # list the repository root

次にClaude に接続します。ターミナルを使いたくない場合は、 Claude Desktop 拡張機能をご利用ください。MCP を初めて使う場合は、 ステップバイステップガイド（約7分）をご覧ください。すぐに使える プロンプトやコマンドをお探しですか？使用例をご覧ください。

できること

接続すると、Claude に次のようなことを尋ねられます。

• 「未払い残高について記載されているリース契約はどれで、何と書かれていますか？」
• 「オンボーディングフォルダーにある最新のドキュメントを要約してください。」
• 「この2つのスキャンは同じ記録ですか、それとも何か違いがありますか？」
• 「2023年の重複請求書を探して、どのくらいの容量を占めているか教えてください。」
• 「この5件のステータスを承認済みに設定してください。」

その裏では、次のことができます。

項目を探す

• ネイティブの Laserfiche クエリや名前のパターンで検索できます。または、リポジトリ独自のテンプレートとフィールド名を使って Claude にクエリを作成させることもできます。Laserfiche がクエリを拒否した場合は、自動的に修正します。
• スキャンを含むドキュメント内を検索します。 全文検索では、Laserfiche の OCR インデックスから一致する箇所（ページ番号とその周辺のテキスト）が直接返されるため、「Xについて何と書かれていますか？」という質問の多くに、ダウンロードせずに回答できます。
• 画像を確認します。 Claude はリポジトリ内の画像ファイル（PNG、JPEG、GIF、WebP）を表示して、独自のタグやテンプレートの標準に沿って説明、分類、タグ付けできます。画像はトークンを消費するため、推定コストを事前にお知らせし、確認を求めます。テキストのスキャンの場合は、画像を確認する前に Laserfiche の OCR を試します。オプションの laserfiche-mcp[images] を使うと、画像の縮小が可能になります。

項目を読む

• フォルダーを参照し、ID やパスで項目を検索し、メタデータ、テンプレートのフィールド値、リポジトリのフィールド／タグ／テンプレート／リンク定義を読み取れます。
• ファイルをダウンロードするか、長いドキュメントではページ範囲を指定してテキストを抽出できます。対応形式は PDF、Word、PowerPoint、メール、HTML、RTF、プレーンテキストです（Excel と Outlook の .msg には pip install 'laserfiche-mcp[office]' が必要です）。

分析する

• 2つの項目のメタデータとフィールドを比較し、バイト単位で同一の重複項目を見つけます（一致するサイズのファイルのみダウンロードされます）。コマンドラインからは、フォルダーツリー全体の一覧を CSV に出力することもできます。

変更する（オプトイン）

• フォルダーを作成し、ドキュメントをインポートし、項目をコピー、名前変更、移動できます。
• フィールド、タグ、リンクを編集（結合または置換）し、テンプレートを割り当てたり解除したりできます。Laserfiche にリクエストを送る前に、必須フィールドを確認します。
• 項目、ファイル、ページ範囲を削除できます。削除、名前変更、移動の前には必ずプレビューを表示します。フォルダーを制限対象にしたり、ツールを許可リストで管理したり、一括削除の上限を設定したりできます。安全性をご覧ください。

必要な場所で実行する

• Claude Desktop または Claude Code 上でローカル実行するか、ワンクリックでインストールできる Desktop 拡張機能として使うか、ユーザーごとのサインインに対応した HTTP サーバーとして claude.ai や ChatGPT で使用できます。
• セルフホストの Laserfiche（Repository API v1 と v2）に対応しています。Cloud はベータ版です。
• AI を使わないコマンドラインツールとしても利用できます。シェルから同じ操作を実行でき、スクリプト向けに --json で出力できます。docs/cli.mdをご覧ください。

各ツールの詳細：docs/tools.md。

インストール

Claude Desktop 拡張機能

ターミナルも設定ファイルも不要です。

1. 拡張機能をダウンロードします（Claude Desktopが必要です）。

2. ダブルクリックし、インストールをクリックして、フォームに入力します。

   フィールド	入力する内容
   Repository API URL	サーバーアドレス（例：https://your-server/LFRepositoryAPI）
   リポジトリ名	Laserfiche Web Access へのサインイン時に選択するリポジトリ
   ユーザー名／パスワード	リポジトリの読み取り権限があるアカウント（パスワードは OS のキーチェーンに保存されます）

   入力する内容がわからない場合は、組織で Laserfiche を管理している担当者にお問い合わせください。

3. *「Accounting フォルダーにある3月の請求書をすべて探してください。」*のように、Claude に尋ねます。

詳しくはdocs/desktop-extension.mdをご覧ください。

Python パッケージ

uvx laserfiche-mcp            # run directly, no install
pip install laserfiche-mcp    # or add it to your environment

Python 3.10 以降と、読み取り権限のあるアカウントでアクセス可能な Laserfiche Repository API Server が必要です。

設定

laserfiche-mcp setup を実行するか、次の環境変数を設定してください。

変数	例	備考
LF_REPO_API_URL	https://lf.example.com/LFRepositoryAPI	お使いの Repository API Server
LF_REPOSITORY_ID	my-repo
LF_API_VERSION	v1（デフォルト）または v2	値が誤っている場合は 400 UnsupportedApiVersion が返されます。curl {LF_REPO_API_URL}/v1/Repositories と /v2/Repositories で確認してください。リポジトリ一覧が返される方がお使いのバージョンです。
LF_USERNAME / LF_PASSWORD		サービスアカウント
LF_AUTH_MODE	password
LF_READ_ONLY	true（デフォルト）	false にすると書き込みツールが有効になります

その他の設定（書き込みガードレール、サイズ制限、検索の調整、ウェブクライアントリンク、ログ記録）については、docs/configuration.md を参照してください。

警告

Laserfiche Cloud のサポートはベータ版であり、実際のテナントでの動作確認は一度も行われていません。Cloud をご利用の場合は、 動作した点や問題があった点を添えて、 issue を作成してください。 詳細は docs/configuration.md を参照してください。

Claude に接続する

Claude Code

claude mcp add laserfiche -- uvx laserfiche-mcp

--env LF_REPO_API_URL=... フラグで設定を渡すか、先にシェルで環境変数をエクスポートしてください。

Claude Desktop — claude_desktop_config.json（Windows では %APPDATA%\Claude\、macOS では ~/Library/Application Support/Claude/）に次の内容を追加し、再起動してください。

{
  "mcpServers": {
    "laserfiche": {
      "command": "uvx",
      "args": ["laserfiche-mcp"],
      "env": {
        "LF_REPO_API_URL": "https://lf.example.com/LFRepositoryAPI",
        "LF_REPOSITORY_ID": "my-repo",
        "LF_API_VERSION": "v1",
        "LF_USERNAME": "service-account",
        "LF_PASSWORD": "replace-me",
        "LF_AUTH_MODE": "password",
        "LF_READ_ONLY": "true"
      }
    }
  }
}

Claude を使わずにツールを試すには、MCP Inspector を使用します。 npx @modelcontextprotocol/inspector uvx laserfiche-mcp

ウェブクライアント（claude.ai、ChatGPT）

デフォルトでは、サーバーは stdio を介してローカルクライアントと通信します。ウェブコネクターからローカルプログラムを起動することはできないため、代わりに HTTP サーバーとして実行してください。

laserfiche-mcp --http          # serves http://127.0.0.1:8000/mcp

ご自身のマシン以外から利用するには、TLS、認証（ユーザーごとの OAuth または共有トークン）、および Laserfiche サーバーへのネットワーク接続が必要です。セットアップとセキュリティチェックリストについては、docs/remote-http.md を参照してください。

コマンドライン

laserfiche-mcp ls '\HR\Leases'                 # list a folder (by path or entry ID)
laserfiche-mcp get 4821 --to ./lease.pdf       # download a document
laserfiche-mcp cat 4821 --pages 4-9            # print its text
laserfiche-mcp search 'unpaid balance'         # full-text search with excerpts
laserfiche-mcp manifest 1 --out inventory.csv  # inventory a folder tree
laserfiche-mcp dedupe 1                        # find byte-identical documents

すべてのコマンドで --json を指定できます。その他の使用例はexamples、完全なリファレンスは docs/cli.md を参照してください。

安全性

• 書き込みはデフォルトで無効です。
• 有効にした場合、対象を特定のフォルダーに限定し（LF_WRITE_PATHS_ALLOW）、使用可能な書き込みツールを制限し（LF_WRITE_TOOLS_ALLOWED）、フォルダーの削除数に上限を設定できます。
• delete、rename、move はプレビューと有効期間の短いトークンを返します。そのトークンを指定して呼び出しを繰り返すまで、変更は適用されません。
• まずはサンドボックスフォルダーで開始してください。書き込みモードの推奨設定を参照してください。

ドキュメントの内容の取り扱いについては、データの取り扱いとプライバシーを参照してください。 すべてのガードレールについては、docs/safety.mdを参照してください。

トラブルシューティング

まずは次のコマンドを実行してください。ログインをテストし、サーバーを確認して、問題の原因を知らせます。

laserfiche-mcp diagnose

症状	考えられる原因	対処方法
diagnose が UNREACHABLE と表示する	URL が間違っている、VPN が停止している、または証明書が内部 CA から発行された https:// サーバー	URL を修正します。内部 CA の場合は LF_USE_SYSTEM_CA=true（または LF_CA_BUNDLE=<pem>）を設定してください。証明書チェックを無効にする LF_VERIFY_SSL=false は設定しないでください
CERTIFICATE_VERIFY_FAILED ... hostname mismatch	URL のホスト名が証明書に記載された名前ではない（短い名前と完全な host.domain 名の違いなど）	LF_REPO_API_URL に証明書に記載されたホスト名を使用します
diagnose が別の API バージョンを提案する	LF_API_VERSION の不一致	表示されたバージョンを使用します
HTTP 401、または Laserfiche エラー 9528	認証情報が無効（9528 の「LFDS unreachable」という説明は誤解を招きます）	laserfiche-mcp setup を再実行します
設定が無視されているように見える	LF_* 名のスペルミス。認識されない名前は通知なしで無視されます	diagnose に、認識されない LF_* 変数が表示されます

Windows では、リポジトリのパスを二重引用符で囲んでください：laserfiche-mcp list "\HR\Leases"。 Claude Desktop のログ：%APPDATA%\Claude\logs\（macOS：~/Library/Logs/Claude/）。

ツールが失敗すると、クラッシュするのではなく、モデルに再試行するか、ユーザーに尋ねるか、処理を諦めるかを伝える構造化エラーを返します。 docs/error-contract.md を参照してください。

ドキュメント

はじめに	MCP を初めて使う方向けの、より詳しい手順
例	コピーして使えるプロンプト、コマンド、設定
設定	すべての LF_* 設定
ツール	すべてのツールとその使い方
コマンドライン	CLI の規則、形式、コスト削減
安全性モデル	書き込みの安全策と確認トークン
データの取り扱いとプライバシー	Claude が参照する情報とデータの送信先
リモート HTTP	Web クライアント、OAuth、ユーザーごとのアクセス
エラー仕様	エラーの種類とコード

ロードマップ

• クラウドでの検証 — 認証フローを最初から最後まで確認するには、Laserfiche Cloud のテナントを持つ方の協力が必要です。
• ユーザーごとのアクセス（ベータ版） — LF_AUTH_MODE=oauth_passthrough は共有アカウントではなく各ユーザーとして Laserfiche を呼び出します。稼働中の LFDS テナントでの確認が必要です（詳細）。
• 監査ログ — すべての書き込み呼び出しを記録するサーバー側ログ。
• v3.0 — 古い動詞先行のツール名（get_entry など）を削除し、laserfiche_{resource}_{verb} のみを残します。
• 今後 — ワークフローのトリガーツール、複数インスタンスのデプロイに向けたステートレス MCP のレビュー。

コントリビューション

課題の報告、提案、PR を歓迎します。次のコマンドでテストを実行してください。

uv sync --extra dev
uv run pytest && uv run ruff check src tests && uv run mypy src

セットアップ方法、特に協力を必要としている内容、オプトイン方式の統合テストについては、CONTRIBUTING.md を参照してください。このプロジェクトは Laserfiche と提携しておらず、承認も受けていません。

所有権とライセンス

これはセブンスデー・アドベンチスト総会が所有するオープンソースプロジェクトであり、保証なしの現状有姿で一般に公開されています。セブンスデー・アドベンチスト総会を代表して Samuel Hernandez が作成・保守しており、保守担当者は本プロジェクトの著作権を保有していません。詳細な条件については、LICENSE ファイルを参照してください。

バグ報告、質問、提案を歓迎します。ぜひ課題を作成してください。