Seafile MCP Server

A Model Context Protocol (MCP) 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 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
Docker Install	Self-host with Docker (recommended)	Docker Guide
Manual Install	Self-host on Linux server	Manual Guide
Synology NAS	Run on Synology NAS	Synology Package
UGREEN NAS	Run on UGREEN NAS via Docker	Docker Guide
Raspberry Pi	Self-host on a Pi	Pi Guide

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

# 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.

# 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

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

Log into your Seafile web interface
Click your avatar/profile icon in the top right
Go to Settings → Web API Auth Token
Click Generate Token or copy your existing token

Option B: Using curl (Command Line)

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:

{"token": "a]1b2c3d4e5f6g7h8i9j0..."}

Copy the token value (without quotes).

Step 5: Configure Your Credentials

# 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

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

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
Add the MCP server configuration:

If the file is empty or doesn't exist, create it with:
```
{
  "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
Restart Claude Desktop completely:
- Quit Claude Desktop (Cmd+Q on Mac, Alt+F4 on Windows)
- Reopen Claude Desktop
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)

Create a .mcp.json file in your project directory:

{
  "mcpServers": {
    "seafile": {
      "command": "/FULL/PATH/TO/seafile-mcp/venv/bin/python",
      "args": ["/FULL/PATH/TO/seafile-mcp/src/server.py"]
    }
  }
}

Start Claude Code in that directory - it will automatically load the MCP server.
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:

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!

Security & Privacy

Important: Please read 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 for responsible disclosure guidelines.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

By participating in this project, you agree to abide by our Code of Conduct.

License

MIT License - See LICENSE file for details.

Author

Setu Kathawate

GitHub: @setugk

Acknowledgments

Built with FastMCP for easy MCP server development
Uses the Seafile Web API