seafile-mcp

Model Context Protocol server for Seafile file storage. Multi-user, with two token-based auth modes and full file/folder/library management.

Built with FastMCP (mcp<2). Inspired by setugk/seafile-mcp (tool coverage), virtUOS/seafile-mcp (multi-user + safety modes) and 5p00kyy/seafile-mcp (dual account/repo-token env config).

Auth: register once, then pass only user_id (tokens only — never passwords)

No tokens are fixed in .env. Each user registers once; the server saves the tokens in a vault file (SEAFILE_VAULT_PATH, default ~/.seafile-mcp/vault.json, mode 0600). All later calls pass only user_id:

1. register_user(user_id="alice", account_token="<token>") — full scope, or register_user(user_id="bob", repo_tokens={"Docs": "<token>"}) — scoped.

2. Use any tool with user_id="alice" — no tokens per call.

3. Maintain with update_account_token, add_library_tokens, remove_library_tokens, remove_account_token, revoke_user; inspect with my_credentials (tokens always masked, never revealed).

Resolution order per call: explicit account_token/repo_token params → vault record for user_id → env defaults (SEAFILE_ACCOUNT_TOKEN / SEAFILE_REPO_TOKENS_JSON, single-user fallback only).

Security note: user_id is self-asserted by the caller — a namespace, not an identity proof. Anyone reaching the endpoint could pass another user's id and use their stored tokens. Protect multi-user HTTP deployments per user (reverse-proxy auth, VPN/Tailscale). For local single-user use, stdio + optional env defaults avoid the vault entirely.

Getting an account token (one-time, never expires)

There is no Web UI page for account tokens. Mint it with your username and password (add -H 'X-SEAFILE-OTP: <6-digit>' if you use 2FA):

curl -d "username=YOUR_EMAIL&password=YOUR_PASSWORD" \
  https://YOUR_SEAFILE_SERVER/api2/auth-token/
# {"token": "24fd3c026886e3121b2ca630805ed425c272cb96"}

The token is permanent — re-mint only after a password change (which invalidates it), then save the new one with update_account_token. The get_auth_help tool repeats these instructions for agents.

Getting a library API token (scoped, r or rw, valid until deleted)

Seafile Web UI: library menu (⋯) → Advanced → API Token → create with read or read-write permission. Or via API with an account token:

curl -H "Authorization: Token <account-token>" -H 'Content-Type: application/json' \
  -d '{"app_name": "my-assistant", "permission": "rw"}' \
  https://YOUR_SEAFILE_SERVER/api/v2.1/repos/<repo-id>/repo-api-tokens/

Related MCP server: Kova Mind MCP Server

Install

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # set SEAFILE_SERVER_URL; tokens are registered at runtime

Requires SEAFILE_SERVER_URL (no trailing slash). Auth header scheme defaults to auto (Token, falling back to Bearer on 401 — covers Seafile < 11 and ≥ 11).

Run

# Local single-user (Claude Desktop / Code / OpenCode)
seafile-mcp --transport stdio

# Multi-user HTTP
seafile-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Put the HTTP endpoint behind a reverse proxy / VPN for remote use — it has no built-in endpoint auth; Seafile tokens travel per tool call.

Client config examples

stdio (claude_desktop_config.json / .mcp.json):

{ "mcpServers": { "seafile": {
  "command": "/abs/path/seafile-mcp/.venv/bin/seafile-mcp",
  "args": ["--transport", "stdio"],
  "env": { "SEAFILE_SERVER_URL": "https://seafile.example.com",
            "SEAFILE_ACCOUNT_TOKEN": "<token>" }
} } }

Streamable HTTP + Docker: cp .env.example .env, set values, docker compose up.

Safety modes (SEAFILE_MCP_MODE)

• read_only — mutating tools are not registered at all.

• safe_write (default) — create/rename/move/copy/upload allowed; deletes hidden.

• full — also registers delete_library (permanent!) and delete_item (to trash).

Overwrites create new versions in Seafile file history; deletes go to library trash. The trash-purge endpoint is deliberately not exposed.

Tools (26)

User vault (all modes): register_user, update_account_token, add_library_tokens, remove_library_tokens, remove_account_token, revoke_user, my_credentials · Help: get_auth_help, resolve_library · Libraries (account only): list_libraries, get_library_info, create_library, rename_library, delete_library (full mode) · Files: list_directory, get_file_detail (account only), read_file, get_download_link, search_files (account only), create_directory, upload_file, update_file, rename_item, move_item (account only), copy_item (account only), delete_item (full mode, account only).

Every file/library tool accepts user_id (vault), repo_id or library_name, plus optional account_token / repo_token overrides (explicit params win over the vault). read_file returns text (truncated with notice) or, for binaries, metadata + download link. upload_file / update_file take text or base64 (is_base64: true).

Tests

.venv/bin/python -m pytest -q   # 40 tests, mocked HTTP (no live server needed)

Roadmap

• PDF/Office text extraction (currently binaries return metadata + link)

• Optional endpoint bearer-auth for the HTTP transport

• Background search index for repo-token libraries (cf. dm7500/seafile-vault-mcp)

License

MIT