seafile-mcp
# seafile-mcp (Seafile MCP connector)
MCP connector for a self-hosted [Seafile](https://github.com/haiwen/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
```bash
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.
```json
{
"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):
```bash
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:
```bash
npm run gen:operations
```
## Config
| Variable | Meaning |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEAFILE_URL` | Required. Self-hosted seahub origin. No default. `seafile.com` hosts are refused. |
| `SEAFILE_TOKEN` | Account token or library API token. Sent as `Authorization: Token`. |
| `SEAFILE_FILE_SERVER_URL` | Optional file-server origin for upload and download URLs that are not on `SEAFILE_URL`. Hosted Seafile domains are refused. |
| `SEAFILE_REVEAL_LINK_TOKENS` | Optional, default off. Set to `true` to show share and upload link tokens and URLs, so a created link can be given out and deleted by token. Account token and passwords stay redacted either way. |
| `SEAFILE_ALLOW_WRITES` | Must be the literal `true` before a confirmed write is sent. |
| `SEAFILE_TOOLSETS` | Comma list of toolsets, or `all`. Default `server,libraries,files_and_dirs,search`. |
| `SEAFILE_PER_MINUTE` | Local request budget. Default 30. |
| `SEAFILE_TIMEOUT_MS` | Upstream timeout. Default 20000. |
| `SEAFILE_CACHE_TTL_SEC` | GET cache TTL. Default 60. Writes clear the cache. |
| `SEAFILE_CONTACT` | Contact token in the User-Agent. |
| `MCP_TRANSPORT` | `stdio` or `http`. `--http` overrides. |
| `PORT` | HTTP port. Default 3000. |
## 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.
| Toolset | Tool | Operations | Default |
| --------------- | ------------------------- | ---------- | ------- |
| server | `seafile_server` | 46 | yes |
| libraries | `seafile_libraries` | 39 | yes |
| files_and_dirs | `seafile_files_and_dirs` | 74 | yes |
| search | `seafile_search` | 6 | yes |
| history_trash | `seafile_history_trash` | 24 | no |
| share_links | `seafile_share_links` | 35 | no |
| upload_links | `seafile_upload_links` | 12 | no |
| library_sharing | `seafile_library_sharing` | 41 | no |
| groups | `seafile_groups` | 54 | no |
| tags | `seafile_tags` | 17 | no |
| starred | `seafile_starred` | 6 | no |
| notifications | `seafile_notifications` | 14 | no |
| activities | `seafile_activities` | 1 | no |
| invitations | `seafile_invitations` | 6 | no |
| address_book | `seafile_address_book` | 5 | no |
| wikis | `seafile_wikis` | 47 | no |
| via_repo_token | `seafile_via_repo_token` | 40 | no |
| ocm | `seafile_ocm` | 8 | no |
| admin_users | `seafile_admin_users` | 20 | no |
| admin_libraries | `seafile_admin_libraries` | 23 | no |
| admin_groups | `seafile_admin_groups` | 14 | no |
| admin_logs | `seafile_admin_logs` | 29 | no |
| admin_shares | `seafile_admin_shares` | 15 | no |
| admin_system | `seafile_admin_system` | 79 | no |
Example. List libraries, preview a create, then confirm it.
```json
{ "action": "list_repos" }
```
```json
{ "action": "create_repo", "body": { "name": "Lab" } }
```
```json
{ "action": "create_repo", "body": { "name": "Lab" }, "confirm": true }
```
Read a text file after you set `SEAFILE_ALLOW_WRITES=true`.
```json
{
"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](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](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).
TDQS
Scored across 4 tools
The four tools split the surface by domain (files/dirs, libraries, search, server), which gives an agent a rough first cut, but boundaries leak: directory and file operations appear in both seafile_files_and_dirs and seafile_libraries, and each tool is a flat bundle of dozens of raw route actions (delete_dir vs delete_repos_dir, get_repo vs get_repos, list_repos vs list_repos_get, post_repo vs update_repos_*) that are hard to tell apart without reading full path semantics. Within each tool the agent must select among 6–74 near-duplicate REST endpoints, so misselection risk is high even though the four top-level buckets are reasonably distinct.
Tool names follow a clean, predictable seafile_<domain> pattern (seafile_files_and_dirs, seafile_libraries, seafile_search, seafile_server) in consistent snake_case. However, the internal action names exposed inside each tool swing between clean task verbs (list_dir, delete_file, search_file) and raw route-derived artifacts (copy_repos_fileops, delete_repos_batch_delete_folders_item, post_repos_sync_batch_copy_item), which undermines the usability of the naming for selection.
Only four tools carry roughly 165 underlying operations (74 + 39 + 6 + 46), so the surface is massively over-compressed into mega-tools rather than scoped by user intent. The tool count is nominally small but functionally far too coarse, forcing agents to navigate huge enumerated action lists for routine operations.
Core areas — library CRUD, file/dir operations, comments, locking, batch copy/move, upload/download links, search, account and server admin — are covered, so basic workflows have no dead ends. But major Seafile domains are absent: sharing/permissions, groups, trash/recycle-bin restore, file revisions, activities/notifications, wikis, and sync, despite sharing-related zip-task endpoints being present.