seafile-vault-mcp

A self-hosted Model Context Protocol (MCP) server that gives Claude read/write access to a Seafile library, turning it into a personal knowledge vault ("Second Brain").

The server exposes MCP tools over Streamable HTTP (HTTP with JSON/SSE), so it works as a remote custom connection from Claude.ai on desktop and mobile.

Features

• Read and write files in a single configured Seafile library

• Directory operations — list, create, delete

• Full-text search across vault contents via SQLite FTS5 (no external search service)

• Persistent search index that survives container restarts

• Background sync re-indexes changed files every 60 seconds

• Bearer token authentication on the MCP endpoint

Related MCP server: md-graph

Prerequisites

• A running Seafile instance (self-hosted or Seafile Cloud)

• A Seafile API token with access to your vault library

• The repository ID of the library you want to expose

• Docker and Docker Compose (recommended), or Python 3.12+

Quick start (Docker)

1. Clone this repository and copy the example environment file:

   cp .env.example .env

2. Edit .env with your Seafile URL, token, repo ID, and a strong MCP_AUTH_TOKEN.

3. Start the server:

   docker compose up -d --build

4. Confirm it is running:

   docker compose logs -f

   On first startup you should see index build progress in the logs. Subsequent restarts load the existing index and run a quick incremental sync.

The MCP endpoint is available at:

http://<your-host>:8000/mcp

MCP tools

Getting a Seafile API token

1. Log in to your Seafile web interface.

2. Open Settings (avatar menu → Settings).

3. Go to the Developer or API section (wording varies by Seafile version).

4. Click Generate new token (or similar).

5. Copy the token into SEAFILE_TOKEN in your .env file.

The token is sent as Authorization: Token <token> to the Seafile API. It is never logged by this server.

Finding your Seafile repo ID

The repo ID is a UUID that identifies a specific library.

Via the web UI: Open the library in Seafile. The URL often contains the repo ID:

https://seafile.example.com/library/<repo-id>/...

Via the API:

curl -H "Authorization: Token YOUR_TOKEN" \
  "https://seafile.example.com/api2/repos/"

Look for your library name in the JSON response and copy its id field into SEAFILE_REPO_ID.

Adding to Claude.ai

1. Deploy the server so it is reachable over HTTPS from the internet (use a reverse proxy such as nginx or Caddy with TLS).

2. In Claude.ai, go to Settings → Connectors (or Integrations).

3. Add a custom MCP server / remote connector.

4. Set the server URL to your public endpoint, including the /mcp path:

   https://mcp.yourdomain.com/mcp

5. When prompted for authentication, provide your MCP_AUTH_TOKEN as a Bearer token.

Claude will connect over Streamable HTTP. The server accepts GET, POST, and DELETE on /mcp.

Environment variables

Local development (without Docker)

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

export SEAFILE_URL=https://seafile.example.com
export SEAFILE_TOKEN=...
export SEAFILE_REPO_ID=...
export MCP_AUTH_TOKEN=...
export INDEX_DB_PATH=./data/index.db

python server.py

Search index

On first startup the server walks the entire configured library and indexes plain-text files (.md, .txt, .py, .json, .yaml, and similar formats).

• The index is stored at INDEX_DB_PATH (persisted via the Docker /data volume).

• Library walks use a single recursive directory listing (recursive=1) when the Seafile server supports it.

• A background thread polls Seafile every 60 seconds and re-indexes changed files.

• Writes and deletes update the index immediately.

search_vault uses a two-pass strategy: multi-word queries first require all terms to match (match_quality: "exact"). If that returns no results, it falls back to matching any term (match_quality: "partial").

Only the single library identified by SEAFILE_REPO_ID is accessible — not your full Seafile account.

Running tests

pip install -r requirements-dev.txt
pytest

Security notes

• Use a long, random MCP_AUTH_TOKEN and terminate TLS at a reverse proxy.

• The server exposes one Seafile library only; repo ID and token are fixed at deploy time.

• Seafile credentials are read from environment variables and are not written to logs.

• CORS is disabled by default. Set MCP_ALLOWED_ORIGINS only if you need browser-based MCP clients.

Project layout

seafile-vault-mcp/
  server.py           MCP server, tools, HTTP transport
  seafile.py          Seafile REST API client
  index.py            SQLite FTS5 index management
  Dockerfile
  docker-compose.yml
  .env.example
  requirements-dev.txt
  tests/
  README.md
  LICENSE

License

MIT