scottnailon/NextCloud-MCP-Server

NextCloud MCP Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to interact with your NextCloud instance. Browse files, search content, read documents, and manage your NextCloud storage directly from your AI conversations.

Features

🔍 Core File Operations

• List Files: Browse directories with detailed metadata
• Read Files: View text file contents
• Search Files: Find files by name or content type
• File Info: Get detailed metadata about any file or folder

📝 File Management

• Upload Files: Add new files (text or binary)
• Create Folders: Organize with new directories
• Move Items: Relocate files and folders
• Copy Items: Duplicate files and folders
• Delete Items: Remove unwanted files and folders

🎯 Smart Features

• Multiple response formats (JSON and Markdown)
• Automatic content truncation for large files
• Human-readable file sizes
• Comprehensive error messages with actionable guidance
• Support for app passwords (recommended)

Installation

1. Install Dependencies

pip install -r requirements.txt

2. Set Environment Variables

Create a .env file or set environment variables:

export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_USERNAME="your_username"
export NEXTCLOUD_PASSWORD="your_app_password"

Important: It's highly recommended to use an App Password instead of your main password:

1. Log into NextCloud web interface
2. Go to Settings → Security
3. Scroll to "Devices & sessions"
4. Create a new app password
5. Use this app password in the NEXTCLOUD_PASSWORD variable

3. Configure Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "nextcloud": {
      "command": "python",
      "args": ["/absolute/path/to/nextcloud_mcp.py"],
      "env": {
        "NEXTCLOUD_URL": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

4. Restart Claude Desktop

Restart Claude Desktop for the changes to take effect.

Usage Examples

Browse Your Files

Show me my NextCloud files

Search for Documents

Search my NextCloud for PDF files about "project plan"

Read a File

Read the file /Documents/notes.txt from NextCloud

Upload a File

Create a new file in NextCloud at /Documents/meeting-notes.md with the content:
[your content here]

Organize Files

Move /temp/report.pdf to /Documents/Reports/2024/report.pdf in NextCloud

Available Tools

Read-Only Tools

Modification Tools

Configuration

Environment Variables

Path Format

• Paths should start with / for the root directory
• Examples:
  • Root: /
  • Documents folder: /Documents
  • Nested file: /Documents/Reports/2024/report.pdf

Security Best Practices

1. Use App Passwords: Always use app passwords instead of your main password
2. Limit Permissions: The app password can be revoked without changing your main password
3. Environment Variables: Never commit credentials to version control
4. HTTPS Only: Always use HTTPS for your NextCloud URL

Troubleshooting

Authentication Errors

Problem: "Authentication failed" messages

Solution:

• Verify your credentials are correct
• Use an app password (not your main password)
• Check that your NextCloud URL is correct
• Ensure you have proper access rights

Path Not Found

Problem: "Path not found" errors

Solution:

• Check path spelling and case sensitivity
• Ensure parent directories exist
• Use forward slashes (/) not backslashes (\)
• Start paths with / for root directory

Connection Issues

Problem: Timeout or connection errors

Solution:

• Verify NextCloud server is accessible
• Check firewall and network settings
• Ensure NEXTCLOUD_URL includes the protocol (https://)
• Test access via web browser first

Development

Running Tests

# Install dev dependencies
pip install -r requirements.txt

# Run the server
python nextcloud_mcp.py

Project Structure

nextcloud-mcp/
├── nextcloud_mcp.py      # Main MCP server implementation
├── requirements.txt      # Python dependencies
├── README.md            # This file
└── .env.example         # Environment variable template

WebDAV API Reference

This server uses NextCloud's WebDAV API. Key endpoints:

• File operations: /remote.php/dav/files/{username}/
• WebDAV methods: PROPFIND, GET, PUT, MKCOL, DELETE, MOVE, COPY, SEARCH

For more information, see:

• NextCloud WebDAV Documentation

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Publishing to PyPI

To share this with the community via pip:

# Build the package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Then users can install with:

pip install mcp-nextcloud

Sharing with the Community

Submit to MCP Registry

1. Create a GitHub repository with this code
2. Add comprehensive documentation
3. Create evaluation tests
4. Submit to https://github.com/modelcontextprotocol/registry

Create npm Package (optional)

For wider distribution, you can also create a TypeScript version.

License

MIT License - See LICENSE file for details

Support

• GitHub Issues: Report bugs and request features
• Documentation: Check NextCloud's official docs
• Community: Join the MCP Discord/forums

Changelog

Version 1.0.0 (Initial Release)

• Core file operations (list, read, search, info)
• File management (upload, create, move, copy, delete)
• JSON and Markdown output formats
• Comprehensive error handling
• App password support
• Content truncation for large files

Author

Built with ❤️ for the MCP community

Ready to get started? Follow the installation steps above and start managing your NextCloud files with AI!