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

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)

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

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:

   {
     "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:

   {
     "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:

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