nextcloud-mcp-server by abdullahMASHUK - MCP Server

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

Click to expand security setup instructions

For enhanced security, create a dedicated app password:

Navigate to NextCloud Settings

NextCloud → Settings → Security → App passwords

Create New App Password
- Enter name: MCP Server
- Click "Create new app password"
- Copy the generated password: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx
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

Claude Desktop Configuration

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

Direct Usage

# Run the MCP server
nextcloud-mcp-server

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

🛠️ Available Tools

📁 File Operations

🔍 test-connection	Test connectivity to your NextCloud server
📋 list-files	List files and directories with metadata
📁 create-directory	Create new directories in NextCloud
🗑️ delete-file	Delete files or directories
⬆️ upload-file	Upload files with base64 encoding
⬇️ download-file	Download files from NextCloud
🔄 move-file	Move or rename files and directories
📄 copy-file	Copy files and directories to new locations
🔍 search-files	Search for files and directories by name or content
📚 get-file-versions	Get version history of a file
🔄 restore-file-version	Restore a specific version of a file

🔗 Sharing Operations

🌐 create-share	Create public links, user, or group shares
📤 list-shares	List and filter existing shares
🗑️ delete-share	Remove shares by ID

📖 Documentation

🎯 Tool Examples

📋 List Files

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

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

⬆️ Upload File

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

🔄 Move File

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

Response: Confirmation message with source and destination paths

📄 Copy File

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

Response: Confirmation message with copy operation details

🔍 Search Files

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

📚 Get File Versions

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

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

🔄 Restore File Version

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

Response: Confirmation of version restoration

🌐 Create Share

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

Setup Development Environment

# 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!

🚀 How to Contribute

🍴 Fork the repository

🌿 Create your feature branch

git checkout -b feature/amazing-feature

💻 Make your changes
✅ Add tests for new features
🧪 Run the test suite
```
npm run test
npm run lint
```

📝 Commit your changes

git commit -m "✨ Add amazing feature"

🚀 Push to your branch

git push origin feature/amazing-feature

🔄 Open a Pull Request

💡 Ways to Contribute

🐛 Bug Reports	✨ Feature Requests	📚 Documentation	🧪 Testing
Found an issue? Report it!	Have an idea? Share it!	Improve docs and examples	Add tests and improve coverage

💖 Support

Show Your Support! ⭐

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

🗣️ Get Help

🔗 Connect With Us

📜 License

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

📈 Changelog

Version History

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