Nextcloud Mcp Server

🌐 NextCloud MCP Server

[](https://badge.fury.io/js/nextcloud-mcp-server) [](https://www.npmjs.com/package/nextcloud-mcp-server) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/)

A professional Model Context Protocol (MCP) server for seamless NextCloud integration

Empower your AI agents with comprehensive NextCloud file management and sharing capabilities

[Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Security](#-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:

1. Navigate to NextCloud Settings

`` NextCloud → Settings → Security → App passwords ``

1. Create New App Password

• Enter name: MCP Server
• Click "Create new app password"
• Copy the generated password: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx

1. 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!

[](https://github.com/abdullahMASHUK/nextcloud-mcp-server/blob/main/CONTRIBUTING.md) [](https://github.com/abdullahMASHUK/nextcloud-mcp-server/pulls)

🚀 How to Contribute

1. 🍴 Fork the repository
2. 🌿 Create your feature branch

``bash git checkout -b feature/amazing-feature ``

1. 💻 Make your changes
2. ✅ Add tests for new features
3. 🧪 Run the test suite

``bash npm run test npm run lint ``

1. 📝 Commit your changes

``bash git commit -m "✨ Add amazing feature" ``

1. 🚀 Push to your branch

``bash git push origin feature/amazing-feature ``

1. 🔄 Open a Pull Request

💡 Ways to Contribute

🐛Bug Reports ✨Feature Requests 📚Documentation 🧪Testing

Found an issue?Report it! Have an idea?Share it! Improve docsand examples Add tests andimprove coverage

---

💖 Support

Show Your Support! ⭐

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

[](https://github.com/abdullahMASHUK/nextcloud-mcp-server/stargazers) [](https://github.com/abdullahMASHUK/nextcloud-mcp-server/network/members)

🗣️ Get Help

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact Maintainer

🔗 Connect With Us

[](https://github.com/abdullahMASHUK) [](https://www.npmjs.com/package/nextcloud-mcp-server)

---

📜 License

MIT License © 2024 Abdullah MASHUK

[](https://opensource.org/licenses/MIT)

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

[📖 Read Full License](./LICENSE)

---

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

[](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abdullahMASHUK
• Source: abdullahMASHUK/nextcloud-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.