# Nextcloud Mcp Server

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-abdullahmashuk-nextcloud-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abdullahMASHUK](https://agentstack.voostack.com/s/abdullahmashuk)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [abdullahMASHUK](https://github.com/abdullahMASHUK)
- **Source:** https://github.com/abdullahMASHUK/nextcloud-mcp-server

## Install

```sh
agentstack add mcp-abdullahmashuk-nextcloud-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
# Install globally for CLI usage
npm install -g nextcloud-mcp-server

# Or install locally in your project
npm install nextcloud-mcp-server
```

### From Source

```bash
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
   ```

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

```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. 🎮 Usage with MCP Clients

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

```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

### 🏗️ Development

Setup Development Environment

```bash
# 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
   ```
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
   ```
8. **🔄 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](https://github.com/abdullahMASHUK/nextcloud-mcp-server#readme)
- 🐛 [Report Issues](https://github.com/abdullahMASHUK/nextcloud-mcp-server/issues)
- 💬 [Discussions](https://github.com/abdullahMASHUK/nextcloud-mcp-server/discussions)
- 📧 [Contact Maintainer](https://github.com/abdullahMASHUK)

### 🔗 Connect With Us

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

---

## 📜 License

**MIT License** © 2024 [Abdullah MASHUK](https://github.com/abdullahMASHUK)

[](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](https://github.com/abdullahMASHUK)**

*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](https://github.com/abdullahMASHUK)
- **Source:** [abdullahMASHUK/nextcloud-mcp-server](https://github.com/abdullahMASHUK/nextcloud-mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-abdullahmashuk-nextcloud-mcp-server
- Seller: https://agentstack.voostack.com/s/abdullahmashuk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.