laserfiche-mcp

<!-- mcp-name: io.github.SamuelSHernandez/laserfiche-mcp -->

# laserfiche-mcp

[![PyPI version](https://img.shields.io/pypi/v/laserfiche-mcp.svg)](https://pypi.org/project/laserfiche-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/laserfiche-mcp.svg)](https://pypi.org/project/laserfiche-mcp/)
[![CI](https://github.com/SamuelSHernandez/laserfiche-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SamuelSHernandez/laserfiche-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-1f6feb.svg)](https://modelcontextprotocol.io)

> **Community project — not affiliated with or endorsed by Laserfiche.**

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets
Claude (Desktop, Code, or any MCP client) search, read, and — when you opt
in — write documents in a self-hosted
[Laserfiche](https://www.laserfiche.com) repository. The same binary is
also a full command-line client (`ls`, `get`, `cat`, `search`, `manifest`,
`dedupe`, ...) for the deterministic work that needs no model at all.

Current release **v2.4.0** — read and write tools for self-hosted Repository
API v1 and v2, BETA Laserfiche Cloud auth, a one-click Claude Desktop
extension, an optional remote HTTP transport with per-user OAuth for web
clients, and a full CLI (`ls`, `get`, `cat`, `search`, `manifest`, `dedupe`,
...) for the deterministic work that needs no model at all. Read-only by
default; write tools register only with `LF_READ_ONLY=false` and are
guarded by path fences and a two-step, parameter-bound confirmation flow.
See the [CHANGELOG](CHANGELOG.md) for per-release notes and the
[roadmap](#roadmap) for what's next.

## Quick start

```bash
uv tool install laserfiche-mcp   # or run ad hoc: uvx laserfiche-mcp
laserfiche-mcp setup             # wizard: server URL + account, then verifies the connection
laserfiche-mcp ls 1              # you're in — list the repository root
```

Then wire it into your MCP client — see
[Claude Desktop](#connect-to-claude-desktop) and
[Claude Code](#connect-to-claude-code) below. Prefer environment variables
over the wizard? See [Configure](#configure). Want a no-terminal install
instead? See the [Claude Desktop extension](#for-everyone--the-claude-desktop-extension).
New to MCP, or want the slower walkthrough? See
[Connecting Claude to a Laserfiche repository](docs/getting-started.md)
(~7 min read).

## What you can do with it

Once connected, Claude can:

**Read** (always available):

- Search the repository with native Laserfiche search syntax, by name pattern, or via the LLM-friendly `search_natural` flow (asks the server for templates first, then runs with automatic 400 repair)
- List the contents of any folder, look up an entry by ID or path, read all template field values, list field/tag/template/link definitions and audit reasons
- Inspect document metadata, fetch the raw edoc as base64, or extract text locally (PDF, DOCX, PPTX, XLSX, EML, HTML, RTF, `text/*`) — all via `get_document_edoc(..., mode=...)`

**Write** (opt-in via `LF_READ_ONLY=false`):

- Create folders, import documents, copy entries (async), rename and move entries
- Set, merge, and clear fields, tags, and links on an entry
- Assign and remove templates — with optional client-side validation of repository-required fields before the API call
- Delete entries (folders cascade), edocs, and specific page ranges — all with a two-step preview→confirm-token flow, HMAC-signed and bound to operation + entry + the operation's own parameters, expiring after 5 minutes

**Operate safely** — every write checks the entry's path against
`LF_WRITE_PATHS_ALLOW` / `LF_WRITE_PATHS_DENY`, folder deletes refuse
unless `force_large_delete=true` when child count exceeds
`LF_DELETE_FOLDER_MAX_DESCENDANTS`, and `LF_WRITE_TOOLS_ALLOWED` can
scope a deployment to e.g. metadata-only writes.

## Install

Two ways to run it, depending on who you are.

### For everyone — the Claude Desktop extension

Chat with your Laserfiche repository from Claude Desktop — no terminal, no config files.

**1. Download**

[**Download the extension**](https://github.com/SamuelSHernandez/laserfiche-mcp/releases/latest/download/laserfiche-mcp.mcpb) (always the newest version), or browse the [latest release](https://github.com/SamuelSHernandez/laserfiche-mcp/releases/latest). You'll need [Claude Desktop](https://claude.ai/download) installed first.

**2. Double-click & connect**

Double-click the file, click **Install**, and fill in the short form that appears:

| Field | What to enter |
|---|---|
| Repository API URL | Your Laserfiche server address, e.g. `https://your-server/LFRepositoryAPI` |
| Repository name | The repository you pick when signing in to Laserfiche Web Access |
| Username | A Laserfiche account that can read the repository |
| Password | That account's password — stored safely in your computer's keychain |

Not sure what goes where? Ask whoever runs Laserfiche at your organization — it takes them a minute.

**3. Ask**

Open a chat and try:

- *"Find every invoice from March in the Accounting folder."*
- *"What's in the Onboarding folder? Summarize the newest document."*
- *"Search for contracts mentioning Acme and list them with dates."*

> [!NOTE]
> Claude can **look, but never change or delete** — the extension is read-only by default, and your password lives in your operating system's keychain, not a text file.

Full walkthrough for end users and team rollouts: [docs/desktop-extension.md](docs/desktop-extension.md).

### For developers — the Python package

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

Requires Python 3.10+ and a reachable Laserfiche **Repository API Server**
(self-hosted) with a service account that can read it, plus any MCP client
(Claude Desktop, Claude Code, MCP Inspector). For local development:

```bash
git clone https://github.com/SamuelSHernandez/laserfiche-mcp
cd laserfiche-mcp
uv sync --extra dev
```

## Configure

Copy the example file and fill in your repository details:

```bash
cp .env.example .env
$EDITOR .env
```

Minimum required variables for self-hosted password-grant auth:

| Variable             | Example                                       |
| -------------------- | --------------------------------------------- |
| `LF_REPO_API_URL`    | `https://lf.example.com/LFRepositoryAPI`      |
| `LF_REPOSITORY_ID`   | `my-repo`                                     |
| `LF_API_VERSION`     | `v1` (default) or `v2` — see below            |
| `LF_USERNAME`        | `service-account`                             |
| `LF_PASSWORD`        | (your service account password)               |
| `LF_AUTH_MODE`       | `password`                                    |
| `LF_READ_ONLY`       | `true` (default — see Writes section below)   |

**Optional — web-client links.** Unset by default, so search/read tools
never emit `web_url`. Cannot be derived from `LF_REPO_API_URL` — copy it by
hand from your own Laserfiche web client (open a document, copy the browser
URL, substitute the entry ID with `{entry_id}`). See `.env.example` for
worked examples. A returned link grants no access by itself: opening it
still requires the *viewer's own* Laserfiche web-client login and is
subject to the repository's entry-level ACLs — useful for staff who have
Laserfiche accounts, useless to an end user who doesn't.

| Variable                            | Default | Purpose                                                                          |
| ------------------------------------ | ------- | -------------------------------------------------------------------------------- |
| `LF_WEB_CLIENT_URL_TEMPLATE`         | unset   | URL template for a Document viewer link, e.g. `https://lf.example.com/Laserfiche/DocView.aspx?repo={repo_id}&id={entry_id}` |
| `LF_WEB_CLIENT_FOLDER_URL_TEMPLATE`  | unset   | Same, for Folder/RecordSeries entries — most web clients browse on a different page than they view a document on |

**Optional write-mode variables** (fences and allowlists default off; the delete batch cap and required-field validation default on — see the [Safety model](#safety-model) section for context):

| Variable                            | Default | Purpose                                                                          |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `LF_READ_ONLY`                      | `true`  | Set `false` to register the write tools                                          |
| `LF_WRITE_PATHS_ALLOW`              | unset   | Comma-separated path prefixes where writes are permitted (case-insensitive)      |
| `LF_WRITE_PATHS_DENY`               | unset   | Comma-separated path prefixes where writes are refused (deny wins over allow)    |
| `LF_WRITE_TOOLS_ALLOWED`            | unset   | Comma-separated write-tool names to scope what registers; e.g. metadata-only     |
| `LF_DELETE_FOLDER_MAX_DESCENDANTS`  | `50`    | Refuse folder deletes above this immediate-child count unless `force_large_delete=true` |
| `LF_REQUIRE_AUDIT_REASON`           | `false` | When `true`, `delete_entry` refuses to execute without `audit_reason_id`         |
| `LF_VALIDATE_REQUIRED_FIELDS`       | `true`  | Validate the target template's own required fields (fields with a `defaultValue` are skipped) client-side before `assign_template` PUTs |
| `LF_VALIDATE_NAMES`                 | `true`  | Pre-flight field / tag / template / link-type names against cached schema definitions; returns `invalid_*_name` instead of an opaque 400 |
| `LF_SCHEMA_CACHE_TTL_SECONDS`       | `300`   | Cache window for the schema-definition lookups that back `LF_VALIDATE_NAMES` and `LF_VALIDATE_REQUIRED_FIELDS`. Set to `0` to disable caching. |
| `LF_IMPO