Seafile-mcp

An MCP server for Seafile, designed for multi-user deployments: one server instance serves many people, and each user supplies their own Seafile API token as the MCP API key.

How authentication works

The Seafile token is the API key. There is no separate account, no registration, and no credential storage — "authenticated" simply means "Seafile accepted this token."

Two kinds of Seafile token work, and the server auto-detects which one you gave it:

Prefer a read-only library token unless you specifically need more. It is the single most effective way to limit what an assistant can do on your behalf.

Confining an account token to one library

Search is the main reason to use an account token: Seafile offers no search endpoint for library tokens, so a library token cannot search at all. If you want search but not account-wide reach, append :repo_id: and the library id to your account token:

abc123def456…:repo_id:8f2c9b10-4d3e-4a7f-9c21-5e6a7b8c9d01

The server splits this apart, sends only the token to Seafile, and confines every tool to that library. The assistant can then omit repo_id entirely, and naming a different library is refused — so an instruction hidden inside a document it reads ("now search my whole account for…") cannot widen the scope.

One thing to be clear about: this confines the assistant, not the token. The string still contains your full account token, so treat it with exactly the care you would treat the bare token — anyone who obtains it and drops the suffix has your whole account. It is no worse than supplying the bare token (which is what you would otherwise paste), but it is not a restricted credential in the way a library token is.

The server is a stateless pass-through: it stores no credentials, keeps no user database, and retains nothing between requests. Isolation between users is structural — each request carries its own token and no per-user state exists to leak.

Related MCP server: git-mcp-server

Safety

Deployments choose a mode via SEAFILE_MCP_MODE; tools outside the active tier are never registered, so a model cannot call what it cannot see.

• read_only — no mutating tools at all.

• safe_write — default. Write, upload, create directory, rename, move, copy. Every one is reversible via Seafile's file history or an inverse operation.

• full — additionally exposes delete.

Nothing this server exposes can irreversibly destroy data: deletes go to the library trash, and overwrites create a new version in file history. The trash purge endpoint is deliberately not wrapped as a tool.

Reading documents

(Under Development)

seafile_read_file extracts real text from PDF, Word, PowerPoint, Excel and OpenDocument (.odt/.ods/.odp) files instead of returning their raw bytes as mojibake. There is no OCR anywhere — a scanned/image-only PDF or a textless slide/sheet comes back with an explicit notice instead of an error or garbage — and formatting, layout, and embedded images are never preserved.

Image files are the exception: they are not converted to text at all. A .png/.jpeg/.gif/.webp/.tiff/.bmp/.heic is returned as an MCP image block, so a vision-capable model simply looks at it — a photo, a screenshot, a diagram, a scan — with no sandbox, no filesystem, and no download step. Large images are downscaled to fit the limits below, and the accompanying text gives the original dimensions and says when detail may have been lost, so the model can tell "I cannot read this label" from "this label is blank". Still no OCR: nothing is transcribed, the picture is simply shown.

PDF pages and PowerPoint slides are chunkable: a bare call returns the whole document/deck, except that one longer than a configurable threshold (15 pages / 20 slides by default) is previewed instead (first 2 pages / first 3 slides), to keep a single call cheap. Pass start_page/end_page or start_slide/end_slide (1-indexed, inclusive) to read a specific range instead. Excel workbooks are chunked by sheet rather than by number: a bare call returns every sheet if there aren't many (5 by default), or just the first if there are — pass sheet_name to read one specific sheet in full. In every case the response's notice field states the true total (pages/slides/sheets) and whether what you got was a preview or everything, so the two are never ambiguous. Word documents are always extracted in full — Word stores no page boundaries in the file itself, so there's no natural unit to chunk by yet.

LibreOffice files are read the same way as their Microsoft counterparts and share their settings: .ods chunks by sheet_name like .xlsx, .odp by start_slide/end_slide like .pptx, and .odt has no page range for the same reason .docx doesn't — neither format stores page boundaries. In .odt, headings are marked with a leading # and tables stay inline where they appear.

A legacy pre-2007 binary Office file (.doc/.xls/.ppt), or a password-protected Office or OpenDocument file, can't be parsed at all and raises a clear error rather than falling through to mojibake.

Plain text, encodings, and long files

Text files are read as UTF-8 unless a byte-order mark says otherwise. A BOM is an explicit declaration inside the file, so honouring it is not encoding detection — this server never guesses a charset. What it does instead is count: any bytes that could not be decoded become U+FFFD, and decode_replacements plus the notice say how many, so a model knows not to quote that passage as the document's wording. This matters most for a German .csv exported by Excel, which is Windows-1252 by default and whose every umlaut would otherwise be silently destroyed.

Any result cut short by the size limit carries next_offset; pass it back as offset to read on. That is the only way to reach the rest of a long Word, .odt, CSV or log file, none of which have a page or sheet to chunk by.

System admins can tune or disable each preview threshold independently:

SEAFILE_MCP_PDF_PREVIEW_THRESHOLD_PAGES=30      # preview only past 30 pages
SEAFILE_MCP_PDF_PREVIEW_THRESHOLD_PAGES=all     # never preview; always extract the whole PDF
SEAFILE_MCP_PPTX_PREVIEW_THRESHOLD_SLIDES=30    # same idea, for PowerPoint slides
SEAFILE_MCP_XLSX_PREVIEW_THRESHOLD_SHEETS=10    # same idea, for Excel sheet counts
SEAFILE_MCP_MAX_DOWNLOAD_MB=30                  # bytes of one file held in memory
SEAFILE_MCP_MAX_IMAGE_EDGE_PX=1568              # long edge an image is scaled down to
SEAFILE_MCP_MAX_IMAGE_MB=5                      # ceiling on the re-encoded image
SEAFILE_MCP_IMAGE_READS=false                   # don't return images at all

SEAFILE_MCP_MAX_DOWNLOAD_MB is a safety limit rather than a tuning knob: one process serves every user, so an unbounded read is an availability problem, not a slow call. Over the limit, text comes back as a prefix flagged truncated, while a PDF or Office document raises — their structure lives at the end of the file, so a prefix cannot be parsed at all — and so does an image, since a prefix of a PNG is an undecodable fragment rather than a smaller picture.

The image limits bound the model's context, not just bandwidth: a tool result goes straight into the context window, and base64 inflates the bytes by a third. Set SEAFILE_MCP_IMAGE_READS=false for a client that cannot render image blocks or a model without vision — images then come back as a short text description and a pointer to seafile_get_download_link, rather than a block the host silently drops. See docs/deploy.md.

Agent skill

skills/seafile-mcp-tools is a skill documenting the tool-selection pitfalls above plus two things this README doesn't cover: saving new PDF/Word/Excel/PowerPoint files, and editing ones that already exist in the library. Both require real code — seafile_write_file will silently corrupt any of them, since it only ever sends UTF-8 text. The skill bundles a tested generator script per format for creating new files; editing an existing one has no bundled script (the change is different every time), but the skill documents the download → edit-with-the-real-library → re-upload round trip.

This MCP server only ever moves file bytes in and out — it never parses, generates, or edits document structure itself. All of that work happens in the agent's own code, not in this server. Concretely: producing or modifying a PDF/Word/Excel/PowerPoint file requires the agent to have a sandbox or other environment where it can execute code (a shell and Python), in addition to this MCP server — without one, these document formats can be neither produced nor modified through this server at all, no matter which tools are enabled.

Running it

See docs/clients.md for client configuration (LibreChat, Claude Desktop, Claude Code, generic HTTP, and local stdio) and docs/deploy.md for the Docker + Caddy deployment.

# local, single user
export SEAFILE_SERVER_URL=https://seafile.example.org
export SEAFILE_API_TOKEN=your_token
uvx seafile-mcp --transport stdio

License

MIT