🌐 NextCloud MCP Server

A professional Model Context Protocol (MCP) server for seamless NextCloud integration

Empower your AI agents with comprehensive NextCloud file management and sharing capabilities

Installation • Quick Start • Features • Documentation • Security

🚀 Features

| 📁 File Management | 🔗 Sharing | 🔒 Security | 🛠️ Developer Experience | |-------------------------|-----------------|------------------|------------------------------| | List, upload, download | Public links | App passwords | Full TypeScript support | | Create directories | User/group shares | Environment variables | Comprehensive tests | | Delete files/folders | Password protection | Secure authentication | Professional documentation | | Move and rename | Expiration dates | HTTPS enforcement | Easy integration |

✨ Key Capabilities

• 🎯 14 Comprehensive Tools - Complete file operations and sharing management
• 🔐 Enhanced Security - Built-in app password support and best practices
• 🏗️ Professional Architecture - TypeScript-first with full type safety
• 📚 Rich Documentation - Detailed guides and examples
• 🔄 WebDAV Integration - Native NextCloud protocol support
• ⚡ High Performance - Optimized for speed and reliability
• 🌍 Universal Compatibility - Works with any NextCloud instance

📦 Installation

From NPM (Recommended)

# Install globally for CLI usage
npm install -g nextcloud-mcp-server

# Or install locally in your project
npm install nextcloud-mcp-server

From Source

git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install
npm run build

🚀 Quick Start

1. 🔐 Setup App Password (Recommended)

For enhanced security, create a dedicated app password:

1. Navigate to NextCloud Settings

   NextCloud → Settings → Security → App passwords

2. Create New App Password

   • Enter name: MCP Server
   • Click "Create new app password"
   • Copy the generated password: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx

3. Why App Passwords?

   • ✅ Limited scope and permissions
   • ✅ Can be revoked independently
   • ✅ No access to your main account
   • ✅ Auditable access logs

2. ⚙️ Configuration

# Copy the environment template
cp .env.example .env

Edit your .env file:

NEXTCLOUD_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password-here  # Use app password!

3. 🎮 Usage with MCP Clients

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nextcloud": {
      "command": "nextcloud-mcp-server",
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}

# Run the MCP server
nextcloud-mcp-server

# Or with Node.js
node build/index.js

🛠️ Available Tools

📁 File Operations

🔗 Sharing Operations

📖 Documentation

🎯 Tool Examples

{
  "name": "list-files",
  "arguments": {
    "path": "/Documents"
  }
}

Response: Returns array of files with metadata (name, size, type, modification date)

{
  "name": "upload-file",
  "arguments": {
    "remotePath": "/documents/report.pdf",
    "content": "JVBERi0xLjQK..."  // base64 encoded content
  }
}

{
  "name": "move-file",
  "arguments": {
    "sourcePath": "/old-location/document.pdf",
    "destinationPath": "/new-location/document.pdf",
    "overwrite": false
  }
}

Response: Confirmation message with source and destination paths

{
  "name": "copy-file",
  "arguments": {
    "sourcePath": "/Documents/template.docx",
    "destinationPath": "/Projects/new-document.docx",
    "overwrite": true
  }
}

Response: Confirmation message with copy operation details

{
  "name": "search-files",
  "arguments": {
    "query": "quarterly report",
    "path": "/Documents",
    "limit": 20,
    "type": "file"
  }
}

Response: Array of matching files with full metadata

Type Options: file, directory, all

{
  "name": "get-file-versions",
  "arguments": {
    "path": "/Documents/important-document.pdf"
  }
}

Response: Array of file versions with timestamps, sizes, and user information

{
  "name": "restore-file-version",
  "arguments": {
    "path": "/Documents/important-document.pdf",
    "versionId": "1672531200"
  }
}

Response: Confirmation of version restoration

{
  "name": "create-share",
  "arguments": {
    "path": "/Documents/presentation.pptx",
    "shareType": 3,
    "password": "secure123",
    "expireDate": "2024-12-31",
    "note": "Shared for team review"
  }
}

Share Types:

• 0 - User share
• 1 - Group share
• 3 - Public link
• 4 - Email share

🏗️ Development

# Clone and install
git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install

# Development commands
npm run dev          # Run with auto-reload
npm run build        # Build TypeScript
npm run test         # Run test suite
npm run lint         # Check code quality
npm run format       # Format code

Project Structure:

src/
├── index.ts              # Main MCP server
├── services/
│   └── nextcloud.ts      # NextCloud API client
├── types.ts              # TypeScript definitions
└── utils/                # Utility functions

__tests__/                # Test suites
build/                    # Compiled output

🔒 Security

🛡️ Best Practices

| ✅ Do | ❌ Don't | |-----------|--------------| | Use app passwords | Use main account password | | Store in environment variables | Hardcode credentials | | Use HTTPS URLs | Use HTTP connections | | Rotate passwords regularly | Keep old passwords | | Monitor access logs | Ignore security events |

🔐 Security Features

• 🔑 App Password Integration - Dedicated authentication tokens
• 🌐 HTTPS Enforcement - Secure connections required
• 📝 Environment Variables - Safe credential storage
• 🔍 Error Handling - No credential exposure in logs
• 🛡️ Permission Scoping - Limited access rights

⚠️ Security Checklist

• [ ] App password created and configured
• [ ] HTTPS enabled on NextCloud server
• [ ] Environment variables properly set
• [ ] .env file added to .gitignore
• [ ] Regular password rotation scheduled

License

MIT License - see LICENSE file for details.

🤝 Contributing

We Welcome Contributions!

1. 🍴 Fork the repository
2. 🌿 Create your feature branch

   git checkout -b feature/amazing-feature

3. 💻 Make your changes
4. ✅ Add tests for new features
5. 🧪 Run the test suite

   npm run test
   npm run lint

6. 📝 Commit your changes

   git commit -m "✨ Add amazing feature"

7. 🚀 Push to your branch

   git push origin feature/amazing-feature

8. 🔄 Open a Pull Request

💡 Ways to Contribute

💖 Support

Show Your Support! ⭐

If this project helped you, please consider giving it a ⭐ on GitHub!

🗣️ Get Help

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact Maintainer

🔗 Connect With Us

📜 License

MIT License © 2024 Abdullah MASHUK

Permission is hereby granted, free of charge, to any person obtaining a copy of this software...

📖 Read Full License

📈 Changelog

🎉 v1.0.3

• 🎨 Beautified README with professional formatting and visual enhancements
• 📊 Added interactive tables, badges, and collapsible sections
• 👤 Updated author information and git configuration
• 🔗 Enhanced navigation with emojis and better organization
• ✨ Improved user experience for npm and GitHub viewers

🚀 v1.0.2

• ✨ Enhanced documentation and README
• 🔒 Added comprehensive security guidelines
• 📝 Improved TypeScript definitions
• 🐛 Bug fixes and stability improvements

🚀 v1.0.1

• 📚 Updated documentation
• 🔧 Configuration improvements
• 🛠️ Build process optimization

🌟 v1.0.0

• 🎊 Initial release
• 📁 Basic file operations (list, upload, download, delete)
• 🔗 Share management (create, list, delete)
• 🔧 TypeScript implementation
• ✅ Comprehensive test coverage
• 📖 Full documentation

Made with ❤️ by Abdullah MASHUK

Building bridges between NextCloud and AI assistants 🌉