Professional NextCloud MCP server for file operations and sharing
npm install 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
---
| ๐ 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 |
- ๐ฏ 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
---
``bashInstall globally for CLI usage
npm install -g nextcloud-mcp-server
$3
`bash
git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install
npm run build
`---
๐ Quick Start
$3
Click to expand security setup instructions
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-xxxxx3. Why App Passwords?
- โ
Limited scope and permissions
- โ
Can be revoked independently
- โ
No access to your main account
- โ
Auditable access logs
$3
`bash
Copy the environment template
cp .env.example .env
`Edit your
.env file:`bash
NEXTCLOUD_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password-here # Use app password!
`$3
Claude Desktop Configuration
Add to your
claude_desktop_config.json:`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
`bash
Run the MCP server
nextcloud-mcp-serverOr with Node.js
node build/index.js
`---
๐ ๏ธ Available Tools
$3
๐ 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
$3
๐ create-share
Create public links, user, or group shares
๐ค list-shares
List and filter existing shares
๐๏ธ delete-share
Remove shares by ID
---
๐ Documentation
$3
๐ List Files
`json
{
"name": "list-files",
"arguments": {
"path": "/Documents"
}
}
`Response: Returns array of files with metadata (name, size, type, modification date)
โฌ๏ธ Upload File
`json
{
"name": "upload-file",
"arguments": {
"remotePath": "/documents/report.pdf",
"content": "JVBERi0xLjQK..." // base64 encoded content
}
}
`
๐ Move File
`json
{
"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
`json
{
"name": "copy-file",
"arguments": {
"sourcePath": "/Documents/template.docx",
"destinationPath": "/Projects/new-document.docx",
"overwrite": true
}
}
`Response: Confirmation message with copy operation details
๐ Search Files
`json
{
"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
`json
{
"name": "get-file-versions",
"arguments": {
"path": "/Documents/important-document.pdf"
}
}
`Response: Array of file versions with timestamps, sizes, and user information
๐ Restore File Version
`json
{
"name": "restore-file-version",
"arguments": {
"path": "/Documents/important-document.pdf",
"versionId": "1672531200"
}
}
`Response: Confirmation of version restoration
๐ Create Share
`json
{
"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$3
Setup Development Environment
`bash
Clone and install
git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm installDevelopment 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
$3
| โ
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 |
$3
- ๐ 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
$3
- [ ] 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
$3


๐ How to Contribute
1. ๐ด Fork the repository
2. ๐ฟ Create your feature branch
`bash
git checkout -b feature/amazing-feature
`
3. ๐ป Make your changes
4. โ
Add tests for new features
5. ๐งช Run the test suite
`bash
npm run test
npm run lint
`
6. ๐ Commit your changes
`bash
git commit -m "โจ Add amazing feature"
`
7. ๐ Push to your branch
`bash
git push origin feature/amazing-feature
``| ๐ 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 |
---
If this project helped you, please consider giving it a โญ on GitHub!


- ๐ Documentation
- ๐ Report Issues
- ๐ฌ Discussions
- ๐ง Contact Maintainer


---
MIT License ยฉ 2024 Abdullah MASHUK

Permission is hereby granted, free of charge, to any person obtaining a copy of this software...
---
Version History
---
Made with โค๏ธ by Abdullah MASHUK
Building bridges between NextCloud and AI assistants ๐

