<div align="center">

🌐 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

</div>

---

🚀 Features

<div align="center">

📁 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

</div>

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

<details> <summary>Click to expand security setup instructions</summary>

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

</details>

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

<details> <summary>Claude Desktop Configuration</summary>

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

</details>

<details> <summary>Direct Usage</summary>

# Run the MCP server
nextcloud-mcp-server

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

</details>

---

🛠️ Available Tools

📁 File Operations

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

🔗 Sharing Operations

<table> <tr> <td><strong>🌐 create-share</strong></td> <td>Create public links, user, or group shares</td> </tr> <tr> <td><strong>📤 list-shares</strong></td> <td>List and filter existing shares</td> </tr> <tr> <td><strong>🗑️ delete-share</strong></td> <td>Remove shares by ID</td> </tr> </table>

---

📖 Documentation

🎯 Tool Examples

<details> <summary><strong>📋 List Files</strong></summary>

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

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

</details>

<details> <summary><strong>⬆️ Upload File</strong></summary>

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

</details>

<details> <summary><strong>🔄 Move File</strong></summary>

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

Response: Confirmation message with source and destination paths

</details>

<details> <summary><strong>📄 Copy File</strong></summary>

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

Response: Confirmation message with copy operation details

</details>

<details> <summary><strong>🔍 Search Files</strong></summary>

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

</details>

<details> <summary><strong>📚 Get File Versions</strong></summary>

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

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

</details>

<details> <summary><strong>🔄 Restore File Version</strong></summary>

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

Response: Confirmation of version restoration

</details>

<details> <summary><strong>🌐 Create Share</strong></summary>

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

</details>

🏗️ Development

<details> <summary>Setup Development Environment</summary>

# 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

</details>

---

🔒 Security

🛡️ Best Practices

<div align="center">

✅ 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

</div>

🔐 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

<div align="center">

We Welcome Contributions!

</div>

<details> <summary>🚀 <strong>How to Contribute</strong></summary>

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

</details>

💡 Ways to Contribute

<table> <tr> <td align="center">🐛<br><strong>Bug Reports</strong></td> <td align="center">✨<br><strong>Feature Requests</strong></td> <td align="center">📚<br><strong>Documentation</strong></td> <td align="center">🧪<br><strong>Testing</strong></td> </tr> <tr> <td align="center">Found an issue?<br>Report it!</td> <td align="center">Have an idea?<br>Share it!</td> <td align="center">Improve docs<br>and examples</td> <td align="center">Add tests and<br>improve coverage</td> </tr> </table>

---

💖 Support

<div align="center">

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

</div>

---

📜 License

<div align="center">

MIT License © 2024 Abdullah MASHUK

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

📖 Read Full License

</div>

---

📈 Changelog

<details> <summary><strong>Version History</strong></summary>

🎉 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

</details>

---

<div align="center">

Made with ❤️ by Abdullah MASHUK

Building bridges between NextCloud and AI assistants 🌉

</div>