🚀 Features

✨ 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)

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

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

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

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

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

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

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

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

🏗️ 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

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

🔐 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

• <input disabled="" type="checkbox"> App password created and configured
• <input disabled="" type="checkbox"> HTTPS enabled on NextCloud server
• <input disabled="" type="checkbox"> Environment variables properly set
• <input disabled="" type="checkbox"> .env file added to .gitignore
• <input disabled="" type="checkbox"> Regular password rotation scheduled

License

MIT License - see LICENSE file for details.

🤝 Contributing

💡 Ways to Contribute

💖 Support

📜 License

📈 Changelog

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.1.0] - 2025-09-03

Added

• 5 new high-priority tools for enhanced NextCloud functionality:
  • move-file: Move or rename files and directories with overwrite support
  • copy-file: Copy files and directories to new locations
  • search-files: Search for files and directories by name or content with filtering
  • get-file-versions: Get version history of files with timestamps and user info
  • restore-file-version: Restore specific versions of files
• Enhanced TypeScript types for new file operations
• Comprehensive test coverage for all new tools (18 total tests passing)
• Updated documentation with examples for all new tools
• Fallback search mechanism when OCS API is unavailable

Changed

• Updated tool count from 9 to 14 comprehensive tools
• Enhanced README with detailed examples for new functionality
• Improved project documentation structure

Technical

• Added new interfaces: MoveFileOptions, CopyFileOptions, SearchOptions, FileVersion
• WebDAV MOVE and COPY method implementations
• NextCloud OCS API integration for search and versioning
• Professional error handling for all new operations

[1.0.2] - 2025-09-01

Changed

• Updated README installation section: "From NPM (when published)" → "From NPM"
• Reflects current published status of the package

[1.0.1] - 2025-09-01

Added

• Comprehensive security documentation for App Password usage
• Step-by-step guide for creating and using NextCloud App Passwords
• Security best practices section in README
• Enhanced environment file with security comments

Security

• IMPORTANT: Strong recommendation to use App Passwords instead of main account passwords
• Added security considerations section with best practices
• Environment security guidelines

[1.0.0] - 2025-09-01

Added

• Initial release of NextCloud MCP Server
• Complete NextCloud WebDAV API integration
• File management operations (list, create, delete, upload, download)
• Share management with support for public links, user shares, and group shares
• Connection testing functionality
• TypeScript implementation with full type safety
• Comprehensive error handling and logging
• Professional npm package structure
• Jest testing framework setup
• ESLint and Prettier configuration

Changed

• Repository configured for personal management under abdullahMASHUK GitHub account
• GitHub Actions CI/CD pipeline
• Complete documentation and usage examples
• MIT license
• Environment variable configuration support

Features

• Connection Testing: Verify connectivity to NextCloud instances
• File Operations:
  • List files and directories with metadata
  • Create directories
  • Delete files and directories
  • Upload files with base64 encoding
  • Download files with base64 output
• Share Management:
  • Create public links with optional password protection
  • Create user and group shares
  • List existing shares with filtering
  • Delete shares by ID
  • Support for expiration dates and notes
• Security: Username/password authentication with secure HTTP client
• Error Handling: Consistent API response format with detailed error messages
• TypeScript: Full type definitions and IntelliSense support

Technical Details

• Built with TypeScript and ES2022 target
• Uses @modelcontextprotocol/sdk for MCP server implementation
• Axios for HTTP client with proper authentication
• xml2js for parsing WebDAV XML responses
• form-data for multipart form uploads
• Comprehensive Jest test suite
• ESLint and Prettier for code quality
• GitHub Actions for automated testing and publishing

Supported NextCloud APIs

• WebDAV API for file operations
• OCS Sharing API for share management
• Status API for connection testing

Browser/Environment Support

• Node.js 18.0.0 or higher
• TypeScript 5.0 or higher
• Works with any NextCloud instance with WebDAV enabled

[Unreleased]

Planned

• Additional authentication methods (OAuth, app passwords)
• Bulk file operations
• Advanced sharing permissions
• File versioning support
• Trash/recycle bin operations
• Activity monitoring
• Webhook support