# Nextcloud MCP Server

[![npm version](https://badge.fury.io/js/nextcloud-mcp-server.svg)](https://badge.fury.io/js/nextcloud-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

A comprehensive Model Context Protocol (MCP) server for Nextcloud integration, providing AI agents with secure access to Nextcloud's file management, sharing, user administration, and system monitoring capabilities.

## Features

### 🗂️ File Management
- **WebDAV Operations**: List, upload, download, delete, move, copy files and folders
- **Directory Navigation**: Browse directory structures with configurable depth
- **Binary File Support**: Handle both text and binary files with base64 encoding
- **Folder Creation**: Create new directories in your Nextcloud instance

### 🔗 Sharing Management
- **Share Creation**: Create user, group, public, and email shares
- **Share Configuration**: Set permissions, passwords, expiration dates, and notes
- **Share Monitoring**: List and monitor all existing shares
- **Share Updates**: Modify existing share settings
- **Share Deletion**: Remove shares when no longer needed

### 👥 User Administration
- **User Management**: Create, read, update, and delete users (admin privileges required)
- **Group Management**: Create groups and manage group memberships
- **User Details**: Access comprehensive user information including quotas and preferences
- **Bulk Operations**: Efficient handling of multiple users and groups

### 🔧 System Monitoring
- **Server Status**: Monitor Nextcloud server health and version information
- **Capabilities**: Access server capabilities and configuration details
- **Security Auditing**: Built-in security audit workflows

### 📋 Workflow Prompts
- **Backup Workflows**: Automated file backup procedures
- **Share Management**: Comprehensive sharing workflows
- **User Administration**: Step-by-step user management processes
- **File Organization**: Smart file categorization and organization
- **Security Audits**: Automated security assessment procedures

## Installation

### Prerequisites
- Node.js 18+
- npm or yarn
- Nextcloud server with API access
- Valid Nextcloud user credentials

### Setup

1. **Clone and install dependencies:**
```bash
git clone https://github.com/mirekdlugosz/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install
```

2. **Configure environment variables:**
Create a `.env` file in the root directory:
```env
NEXTCLOUD_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-password-or-app-password
```

> **Security Note**: It's recommended to use App Passwords instead of your main password. Generate one in Nextcloud Settings → Security → Devices & sessions.

3. **Build the project:**
```bash
npm run build
```

4. **Test the server:**
```bash
npm start
```

## Usage with Claude Desktop

Add the following configuration to your Claude Desktop config file:

### macOS
`~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows
`%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "nextcloud": {
      "command": "node",
      "args": ["/path/to/nextcloud-mcp-server/dist/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-password-or-app-password"
      }
    }
  }
}
```

## Available Tools (37 total)

### File Operations (7)
- `nextcloud_list_files` - List files and folders
- `nextcloud_upload_file` - Upload files to Nextcloud
- `nextcloud_download_file` - Download files from Nextcloud
- `nextcloud_delete_file` - Delete files or folders
- `nextcloud_move_file` - Move or rename files/folders
- `nextcloud_copy_file` - Copy files or folders
- `nextcloud_create_folder` - Create new folders

### Share Management (4)
- `nextcloud_list_shares` - List all shares
- `nextcloud_create_share` - Create new shares
- `nextcloud_update_share` - Update existing shares
- `nextcloud_delete_share` - Delete shares

### User Management (7)
- `nextcloud_list_users` - List all users
- `nextcloud_get_user` - Get user details
- `nextcloud_create_user` - Create new users
- `nextcloud_update_user` - Update user information
- `nextcloud_delete_user` - Delete users
- `nextcloud_enable_user` - Enable disabled user accounts ⭐ **NEW**
- `nextcloud_disable_user` - Disable user accounts (preserves data) ⭐ **NEW**

### Group Management (6)
- `nextcloud_list_groups` - List all groups
- `nextcloud_create_group` - Create new groups
- `nextcloud_delete_group` - Delete groups ⭐ **NEW**
- `nextcloud_add_user_to_group` - Add users to groups
- `nextcloud_remove_user_from_group` - Remove users from groups
- `nextcloud_get_group_users` - Get all users in a group ⭐ **NEW**

### System Information (3)
- `nextcloud_get_server_status` - Get server status
- `nextcloud_get_capabilities` - Get server capabilities
- `nextcloud_test_connection` - Test connection and verify credentials

### Comments (3)
- `nextcloud_list_comments` - List comments for a file
- `nextcloud_add_comment` - Add comment to a file
- `nextcloud_delete_comment` - Delete a comment from a file

### Local File Management (5)
- `nextcloud_download_to_local` - Download files to local folder for direct Claude access
- `nextcloud_list_local_files` - List files in local downloads folder
- `nextcloud_delete_local_file` - Delete files from local folder
- `nextcloud_upload_from_local` - Upload files from local folder to Nextcloud
- `nextcloud_get_downloads_path` - Get path to downloads folder

### Activity Monitoring (2) ⭐ **NEW CATEGORY**
- `nextcloud_list_activities` - List recent activities (uploads, shares, downloads, etc.)
- `nextcloud_get_activity_types` - Get available activity types and filters

## 🆕 Recent Updates (2025-08-06)

### New Tools Added:
1. **`nextcloud_get_group_users`** - Get all users in a specific group
2. **`nextcloud_delete_group`** - Delete groups from Nextcloud
3. **`nextcloud_list_activities`** - Monitor Nextcloud activities (NEW CATEGORY)
4. **`nextcloud_get_activity_types`** - Get available activity filters
5. **`nextcloud_enable_user`** - Enable disabled user accounts ⭐ **LATEST**
6. **`nextcloud_disable_user`** - Disable user accounts (preserves data) ⭐ **LATEST**

### New Capabilities:
- **Complete User Management**: Full lifecycle including enable/disable operations
- **Complete Group Management**: Now includes listing group members and deleting groups
- **Activity Monitoring**: Track file uploads, downloads, shares, user actions, security events
- **Enhanced Security**: Temporary account suspension without data loss
- **Enhanced User Experience**: Better organization with 37 total tools across 7 categories

## Available Resources

- `nextcloud://files` - Root directory file listing
- `nextcloud://shares` - All shares overview
- `nextcloud://users` - All users listing
- `nextcloud://groups` - All groups listing
- `nextcloud://status` - Server status information
- `nextcloud://capabilities` - Server capabilities

## Available Prompts

- `backup_files` - Create comprehensive backup workflows
- `share_management` - Manage file sharing with detailed options
- `user_administration` - Complete user management workflows
- `file_organization` - Organize files with smart categorization
- `security_audit` - Perform security audits of shares and permissions

## Local File Management System

The server includes an efficient local file management system that allows Claude to work with files directly:

### How it works:
1. **Download to Local**: Files are downloaded from Nextcloud to a local `downloads/` folder
2. **Direct Access**: Claude can access these files directly using standard file operations
3. **Efficient Processing**: No need for base64 encoding/decoding for large files
4. **Upload Back**: Modified files can be uploaded back to Nextcloud

### Benefits:
- **Performance**: Much faster than base64 encoding for large files
- **Memory Efficient**: No need to load entire files into memory as base64
- **Claude Integration**: Claude can use standard file tools to read, edit, and process documents
- **Workflow Flexibility**: Download → Process → Upload workflow

### Example Workflow:
```
1. Download PDF from Nextcloud to local folder
2. Claude reads and analyzes the PDF directly
3. Claude creates a summary or modified version
4. Upload the new file back to Nextcloud
```

## API Compatibility

This MCP server supports Nextcloud API versions 28.0+ and is compatible with:
- **WebDAV API** - For file operations
- **OCS API v1/v2** - For sharing and user management
- **Status API** - For server monitoring
- **Comments API** - For file comments

## Security Considerations

- **App Passwords**: Always use App Passwords instead of main account passwords
- **Permissions**: Some operations require admin privileges
- **Network Security**: Ensure HTTPS is used for Nextcloud connections
- **Access Control**: The server respects Nextcloud's built-in access controls
- **Audit Trails**: All operations are logged by Nextcloud

## Error Handling

The server provides comprehensive error handling for:
- Network connectivity issues
- Authentication failures
- Permission denied errors
- File not found errors
- Invalid parameters
- Nextcloud API errors

## Development

### Building
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Linting
```bash
npm run lint
npm run lint:fix
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
1. Check the Nextcloud API documentation
2. Review the error messages in the MCP server logs
3. Ensure your Nextcloud instance is accessible and credentials are correct
4. Verify that your user has the necessary permissions for the operations you're trying to perform