🌐 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 🌉