# Seafile MCP Server
[](https://github.com/setugk)
[](LICENSE)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects Claude to your Seafile file storage. This lets you ask Claude to browse, search, read, and manage files on your self-hosted Seafile server using natural language.
---
## What is Seafile?
[Seafile](https://www.seafile.com/) is an open-source, self-hosted file sync and share platform - similar to Dropbox or Google Drive, but you control your own data. It's popular for personal use, teams, and enterprises who want privacy and control over their files.
**Why Seafile?**
- **Self-hosted**: Your files stay on your own server
- **Privacy-focused**: No third-party access to your data
- **Fast sync**: Efficient file synchronization across devices
- **Libraries**: Organize files into encrypted or unencrypted libraries
- **Cross-platform**: Apps for Windows, Mac, Linux, iOS, Android
**Don't have Seafile yet?** Here's how to get started:
| Option | Description | Link |
|--------|-------------|------|
| **Seafile Cloud** | Hosted by Seafile (easiest) | [cloud.seafile.com](https://cloud.seafile.com/) |
| **Docker Install** | Self-host with Docker (recommended) | [Docker Guide](https://manual.seafile.com/docker/deploy_seafile_with_docker/) |
| **Manual Install** | Self-host on Linux server | [Manual Guide](https://manual.seafile.com/deploy/) |
| **Synology NAS** | Run on Synology NAS | [Synology Package](https://www.seafile.com/en/download/) |
| **UGREEN NAS** | Run on UGREEN NAS via Docker | [Docker Guide](https://manual.seafile.com/docker/deploy_seafile_with_docker/) |
| **Raspberry Pi** | Self-host on a Pi | [Pi Guide](https://manual.seafile.com/deploy/deploy_with_raspberrypi/) |
### Why This MCP Server?
- **Direct connection** - Connects straight to your Seafile server, no middleman
- **Privacy-first** - Your data never leaves your infrastructure
- **Free & open source** - No subscriptions, no vendor lock-in
- **Full control** - Inspect, modify, and extend the code as needed
- **Self-hosted** - Runs locally alongside your self-hosted Seafile
---
## What can you do with this MCP server?
Once set up, you can ask Claude things like:
**Document Lookups**
- "What are my flight details for the Hawaii trip?"
- "When is my car rental pickup?"
- "Find my tax files from 2024"
- "What's in my Immigration folder?"
- "Show me my recent receipts"
- "List all of Mom's travel folders"
- "Find Dad's visa documents"
**Organization**
- "Create a new folder called '2025 Taxes'"
- "Move the completed trip to Archive"
- "What's in my 'Ideas' folder?"
**Quick Search**
- "Find all PDFs related to insurance"
- "Which folders were modified this month?"
- "Do I have a copy of my lease agreement?"
## Features
| Feature | Description |
|---------|-------------|
| **Browse Libraries** | List all libraries, view library details |
| **Navigate Folders** | List directory contents at any path |
| **Read Files** | Read text file contents directly |
| **File Operations** | Create, rename, move, copy, delete files and folders |
| **Download Links** | Generate download links for any file |
| **Upload Links** | Get upload links for directories |
| **Search** | Search for files across libraries (if enabled on your server) |
---
## Prerequisites
Before you start, make sure you have:
- **Python 3.10 or higher** - Check with `python3 --version`
- **A Seafile server** - Either self-hosted or a Seafile cloud account
- **Claude Desktop app** or **Claude Code CLI** - Where you'll use this MCP server
---
## Installation
### Step 1: Clone or Download This Repository
```bash
# Option A: Clone with git
git clone https://github.com/setugk/seafile-mcp.git
cd seafile-mcp
# Option B: Or download and extract the ZIP, then cd into it
```
### Step 2: Create a Virtual Environment
A virtual environment keeps this project's dependencies isolated from your system Python.
```bash
# Create the virtual environment
python3 -m venv venv
# Activate it
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
```
You should see `(venv)` at the start of your terminal prompt. This means the virtual environment is active.
### Step 3: Install Dependencies
```bash
pip install -r requirements.txt
```
This installs:
- `mcp` - The Model Context Protocol library
- `httpx` - For making HTTP requests to Seafile
- `python-dotenv` - For loading configuration from `.env`
### Step 4: Get Your Seafile API Token
You need an API token to authenticate with your Seafile server.
#### Option A: Using the Seafile Web Interface
1. Log into your Seafile web interface
2. Click your avatar/profile icon in the top right
3. Go to **Settings** → **Web API Auth Token**
4. Click **Generate Token** or copy your existing token
#### Option B: Using curl (Command Line)
```bash
curl -d "username=YOUR_EMAIL&password=YOUR_PASSWORD" \
https://YOUR_SEAFILE_SERVER/api2/auth-token/
```
Replace:
- `YOUR_EMAIL` - Your Seafile login email
- `YOUR_PASSWORD` - Your Seafile password
- `YOUR_SEAFILE_SERVER` - Your Seafile server URL (e.g., `cloud.seafile.com`)
The response will look like:
```json
{"token": "a]1b2c3d4e5f6g7h8i9j0..."}
```
Copy the token value (without quotes).
### Step 5: Configure Your Credentials
```bash
# Copy the example config
cp .env.example .env
# Edit .env with your favorite editor
nano .env # or vim, code, etc.
```
Fill in your values:
```
SEAFILE_URL=https://your-seafile-server.com
SEAFILE_TOKEN=your-api-token-here
```
**Important:**
- No trailing slash on the URL
- No quotes around values
- Keep this file secret (it's already in `.gitignore`)
### Step 6: Test the Server
```bash
python src/server.py
```
If everything is set up correctly, the server will start without errors. Press `Ctrl+C` to stop it.
---
## Connecting to Claude
Choose the method that matches how you use Claude:
### Option A: Claude Desktop App
1. **Find your Claude Desktop config file:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Or in Claude Desktop: `Claude` menu → `Settings` → `Developer` → `Edit Config`
2. **Add the MCP server configuration:**
If the file is empty or doesn't exist, create it with:
```json
{
"mcpServers": {
"seafile": {
"command": "/FULL/PATH/TO/seafile-mcp/venv/bin/python",
"args": ["/FULL/PATH/TO/seafile-mcp/src/server.py"]
}
}
}
```
If you already have other MCP servers, add `seafile` inside the existing `mcpServers` object.
**Important:** Replace `/FULL/PATH/TO/` with the actual absolute path to where you cloned this repo.
Example paths:
- macOS: `/Users/yourname/projects/seafile-mcp/venv/bin/python`
- Windows: `C:\\Users\\yourname\\projects\\seafile-mcp\\venv\\Scripts\\python.exe`
3. **Restart Claude Desktop completely:**
- Quit Claude Desktop (Cmd+Q on Mac, Alt+F4 on Windows)
- Reopen Claude Desktop
4. **Verify it works:**
- Start a new conversation
- Look for the hammer/tools icon - "seafile" should be listed
- Ask: "Use the hello tool" or "List my Seafile libraries"
### Option B: Claude Code (CLI)
1. **Create a `.mcp.json` file** in your project directory:
```json
{
"mcpServers": {
"seafile": {
"command": "/FULL/PATH/TO/seafile-mcp/venv/bin/python",
"args": ["/FULL/PATH/TO/seafile-mcp/src/server.py"]
}
}
}
```
2. **Start Claude Code** in that directory - it will automatically load the MCP server.
3. **Test with:** "List my Seafile libraries"
---
## Available Tools
Once connected, Claude has access to these tools:
| Tool | Description |
|------|-------------|
| `hello` | Test that the MCP server is working |
| `ping_server` | Test connection to your Seafile server |
| `get_account_info` | Get your Seafile account information |
| `list_libraries` | List all your libraries/repos |
| `get_library` | Get details of a specific library |
| `list_directory` | List contents of a folder |
| `create_library` | Create a new library |
| `delete_library` | Delete a library (permanent!) |
| `create_directory` | Create a new folder |
| `delete_item` | Delete a file or folder |
| `rename_item` | Rename a file or folder |
| `move_item` | Move a file or folder |
| `copy_item` | Copy a file or folder |
| `get_file_content` | Read a text file's contents |
| `get_file_download_link` | Get a download URL for a file |
| `get_upload_link` | Get an upload URL for a folder |
| `search_files` | Search for files (requires search enabled on server) |
---
## Troubleshooting
### "Server not appearing in Claude Desktop"
- Double-check the paths in your config are absolute paths (start with `/` on Mac/Linux or `C:\` on Windows)
- Make sure you fully restarted Claude Desktop (not just closed the window)
- Check for JSON syntax errors in your config file (missing commas, brackets)
### "SEAFILE_URL or SEAFILE_TOKEN not configured"
- Make sure you created the `.env` file (not just `.env.example`)
- Make sure the `.env` file is in the project root directory (same folder as `src/`)
- Check there are no extra spaces or quotes in your `.env` values
### "Connection error: Could not reach server"
- Verify your Seafile server URL is correct and accessible
- Try opening the URL in a browser
- Check if your server requires VPN access
### "Authentication failed" or "401 Unauthorized"
- Your API token may have expired - generate a new one
- Make sure you copied the full token with no extra spaces
### "Module not found" errors
- Make sure you're using the Python from the virtual environment in your config
- Run `venv/bin/pip list` to verify `mcp` and `httpx` are installed
### Check server logs
Run the server manually to see any errors:
```bash
source venv/bin/activate
python src/server.py
```
---
## Roadmap
Features planned for future releases:
| Feature | Status | Description |
|---------|--------|-------------|
| **PDF reading** | Planned | Extract text from PDF files so Claude can answer questions about receipts, contracts, etc. |
| **Image OCR** | Idea | Extract text from images using OCR |
| **File upload** | Idea | Upload files to Seafile via Claude |
Have a feature request? [Open an issue](https://github.com/setugk/seafile-mcp/issues)!
---
## Security & Privacy
> **Important:** Please read [SECURITY.md](SECURITY.md) for full security considerations.
### Protecting Your Credentials
- **Never commit your `.env` file** - It contains your API token
- **Secure file permissions** - Run `chmod 600 .env` to restrict access
- **Rotate tokens periodically** - Generate new tokens and revoke old ones
- **Use HTTPS** - Always connect to your Seafile server over HTTPS
### What Claude Can See
When using this MCP server:
- Claude sees **file and folder names** when you browse
- Claude sees **file contents** when you ask to read them
- Conversations are processed by Anthropic's servers
**Best practice:** Avoid asking Claude to read highly sensitive files (passwords, private keys, financial account numbers).
### What Claude Can Do
The MCP server allows Claude to:
- Browse, read, and search files
- Create, rename, move, copy, and **delete** files/folders
**Be careful with destructive commands.** Consider using a read-only API token if your Seafile server supports scoped permissions.
### Local Machine Security
- The MCP server runs locally with your user permissions
- Anyone with access to your machine could read your `.env` file
- Use standard device security (lock screen, disk encryption)
**Reporting vulnerabilities:** See [SECURITY.md](SECURITY.md) for responsible disclosure guidelines.
---
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
---
## License
MIT License - See LICENSE file for details.
---
## Author
**Setu Kathawate**
- GitHub: [@setugk](https://github.com/setugk)
## Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp) for easy MCP server development
- Uses the [Seafile Web API](https://download.seafile.com/published/web-api/home.md)
