🌐 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

✨ 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

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