laserfiche-mcp

laserfiche-mcp

归基督复临安息日会总会所有。与 Laserfiche 无关联，也未获其认可。

让 Claude（Desktop、Code 或任何 MCP 客户端）搜索和读取可自托管的 Laserfiche 存储库中的文档；如果你选择启用， 还可以修改这些文档。同一程序也可作为命令行工具（ls、cat、 search、dedupe 等），用于完全不需要 AI 的工作。

默认只读。 在设置 LF_READ_ONLY=false 之前，写入功能处于关闭状态， 而破坏性操作始终需要经过第二步确认。 当前版本：v2.6.2 — 请参阅 CHANGELOG。

快速开始

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 提出这样的问题：

• “哪些租约提到了未付余额？具体怎么说？”
• “总结 Onboarding 文件夹中最新的文档。”
• “这两份扫描件是同一条记录吗？还是有什么不同？”
• “查找 2023 年下的重复发票，并告诉我它们占用了多少空间。”
• “将这五条记录的 Status 设置为 Approved。”

它可以在后台执行以下操作：

查找内容

• 使用原生 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]'）；处理长文档时可指定页码范围。

分析

• 比较两条记录的元数据和字段，并查找内容逐字节相同的重复文件（仅当文件大小相同时才会下载）。使用命令行还可以将整个文件夹树清单导出为 CSV。

进行更改（需选择启用）

• 创建文件夹、导入文档、复制、重命名和移动条目。
• 编辑字段、标签和链接（合并或替换），并分配或清除模板；发送请求前会检查必填字段。
• 删除条目、文件或页码范围。删除、重命名和移动操作始终会先显示预览；可以限制文件夹范围、将工具加入允许列表，并限制批量删除数量。请参阅安全。

按需运行

• 在 Claude Desktop 或 Claude Code 本地运行，作为一键安装的 Desktop 扩展运行，或作为 HTTP 服务供 claude.ai 和 ChatGPT 使用，并支持每位用户单独登录。
• 支持可自托管的 Laserfiche（Repository API v1 和 v2）；Cloud 支持仍处于 beta 阶段。
• 作为命令行工具运行，无需使用 AI——可在 shell 中执行相同操作，并使用 --json 输出供脚本处理。请参阅 docs/cli.md。

所有工具及其详细信息：docs/tools.md。

安装

Claude Desktop 扩展

无需终端，无需配置文件。

1. 下载扩展（需要安装 Claude Desktop）。

2. 双击该文件，点击 Install，然后填写表单：

   字段	填写内容
   Repository API URL	你的服务器地址，例如 https://your-server/LFRepositoryAPI
   Repository name	登录 Laserfiche Web Access 时选择的存储库
   Username / Password	可读取存储库的账户（密码将存储在操作系统的密钥链中）

   不确定该填写什么？请询问负责管理你所在组织 Laserfiche 的人员。

3. 向 Claude 提出问题，例如 “查找 Accounting 文件夹中 3 月份的所有发票。”

详细信息：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 会启用写入工具

其他所有设置——写入防护、大小限制、搜索调优、Web 客户端链接、日志记录——均见 docs/configuration.md。

警告

Laserfiche Cloud 支持仍处于 beta 阶段，且从未在实际租户上验证过。如果你有 Cloud 访问权限，请通过 提交 issue 告知哪些有效或无效。详情见 docs/configuration.md。

连接到 Claude

Claude Code

claude mcp add laserfiche -- uvx laserfiche-mcp

使用 --env LF_REPO_API_URL=... 标志传递设置，或先在 shell 中导出这些变量。

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

Web 客户端（claude.ai、ChatGPT）

默认情况下，服务通过 stdio 与本地客户端通信。Web 连接器无法 启动本地程序，因此请改为将其作为 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 未连接，或 https:// 服务器使用内部 CA 颁发的证书	修正 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 不可访问”的说法具有误导性）	重新运行 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 文件。

欢迎并感谢提交错误报告、提问和建议——请提交问题。