seafile-mcp (Seafile MCP connector)

MCP connector for a self-hosted Seafile server (seahub). It speaks the seahub HTTP API over stdio and over stateless Streamable HTTP on localhost.

Seafile server is GPLv2. This connector is MIT. It only calls the HTTP API on the server you configure. It is not affiliated with Seafile Ltd. Bring your own account token or library API token.

seafile.routes.json is a route table derived with ast from haiwen/seahub v14.0.9-server (seahub/urls.py and seahub/api2/urls.py). It is not an official OpenAPI document, and it has no request body schemas. The connector covers all 655 routes in that table (/api2/* and /api/v2.1/*). Routes are grouped into 24 toolsets. SEAFILE_TOOLSETS selects a subset. The default set is small and read-focused. all enables every toolset, including admin.

There is no default base URL. SEAFILE_URL is required. Hosts on seafile.com, including cloud.seafile.com, are refused.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.

Create a token with POST /api2/auth-token/ on your server, or create a library API token in the Seafile UI. Put it in SEAFILE_TOKEN. The connector sends Authorization: Token and never prints the token. It does not store a username or password. A library API token cannot delete, move, or copy.

{
  "mcpServers": {
    "seafile": {
      "command": "node",
      "args": ["/workspace/connectors/seafile/dist/index.js"],
      "env": {
        "SEAFILE_URL": "http://127.0.0.1:8000",
        "SEAFILE_TOKEN": "...",
        "SEAFILE_ALLOW_WRITES": "false",
        "SEAFILE_TOOLSETS": "server,libraries,files_and_dirs,search",
        "SEAFILE_CONTACT": "you@example.com"
      }
    }
  }
}

If the file server is on another origin than SEAFILE_URL, set SEAFILE_FILE_SERVER_URL to that origin (often port 8082). read_text_file and write_text_file fetch only that origin, the SEAFILE_URL origin, or a /seafhttp path on the same host. They do not follow redirects to any other host.

Docker (HTTP, no authentication, localhost only):

docker build -t seafile-mcp .
docker run -p 3000:3000 \
  -e SEAFILE_URL=http://host.docker.internal:8000 \
  -e SEAFILE_TOKEN=... \
  seafile-mcp

Do not put the token in the image.

Regenerate the operations registry after a route-table bump:

npm run gen:operations

Related MCP server: paperclip-mcp

Config

Safety

Every non-GET route is a write. So is any GET that mints a download URL, upload URL, update URL, auth token, WebDAV secret, SSO link, or similar credential. A write needs confirm set to the boolean true and SEAFILE_ALLOW_WRITES=true. Otherwise the tool returns a dry-run preview of the method, path, query, and redacted body, and it sends nothing. The string "true" and the boolean false are rejected.

Delete, purge, expire, revert, trash clean, move, copy, and overwrite previews name the library id and the path. The same warning is in the tool description for destructive and credential actions.

read_text_file and write_text_file are extra actions on seafile_files_and_dirs. Both are gated. They stay inside one library path (absolute, no ..). Text only. 256 KiB cap. write_text_file replace defaults to false. replace: true adds an overwrite warning and names the target.

Responses are parsed as JSON objects, arrays (items), or strings (value). stack and traceback fields are dropped. Error text drops server stack traces and filesystem paths. Field names for tokens, passwords, pwd_hash, magic, and random_key are redacted. Share-link and file-server tokens in URLs are redacted. repo_id is kept.

HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 404 is not found. HTTP 400 and 422 are invalid. HTTP 429 is rate limited and includes Retry-After. HTTP 5xx is a server error. Connection failures are network errors. Timeouts are timeouts.

/api2/ bodies are sent as form fields. /api/v2.1/ bodies are sent as JSON. Query object and body object are free-form because the route table has no schemas.

Tools

Default SEAFILE_TOOLSETS publishes 4 tools. SEAFILE_TOOLSETS=all publishes 24 tools (655 route operations, plus read_text_file and write_text_file on the files tool). Each tool takes action plus params, query, body, and confirm when the tool can write.

Example. List libraries, preview a create, then confirm it.

{ "action": "list_repos" }

{ "action": "create_repo", "body": { "name": "Lab" } }

{ "action": "create_repo", "body": { "name": "Lab" }, "confirm": true }

Read a text file after you set SEAFILE_ALLOW_WRITES=true.

{
  "action": "read_text_file",
  "params": { "repo_id": "REPO" },
  "query": { "p": "/notes/a.txt" },
  "confirm": true
}

Live check

npm run live-check and npm run live-check:extra talk to a real Seafile server when SEAFILE_URL and SEAFILE_TOKEN are set (SEAFILE_FILE_SERVER_URL too, if the fileserver is on another origin). They were run against a real local Seafile 9.0.10 server: failed=0, 59 checks. See LIVE-CHECK.md for exactly what was and was not exercised. They print pass and fail lines only and never the token.

This session did not run the live check. The parent runs it against a local server.

What this is not

This is not a Seafile desktop sync client. It does not watch folders or speak the sync protocol.

This is not a client for Seafile Cloud or any seafile.com host.

This is not an official OpenAPI SDK. Body fields come from seahub view code for the common routes and are free-form everywhere else.

This connector does not keep your password, and it does not turn a library API token into an account token. POST /api2/auth-token/ is a gated credential write. Its token is redacted in the result.

Admin toolsets are off unless you set SEAFILE_TOOLSETS.

Attribution

Seafile server is GPLv2. This connector is MIT and is not a derivative of the Seafile server. It is an independent HTTP client of the seahub API.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Seafile project or its owners.

seafile.routes.json is a route table derived from haiwen/seahub (Apache-2.0).