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:

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

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:

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:

Have a feature request? Open an issue!

Security

Important: Please read SECURITY.md for full security considerations.

Key points:

• Never commit your .env file - It contains your API token
• API tokens grant full access to your Seafile account - treat them like passwords
• Review the code before running - inspect src/server.py to understand what it does
• Secure file permissions - Run chmod 600 .env to restrict access to your credentials
• Consider token scope - Some Seafile deployments support scoped tokens with limited permissions

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