Skip to main content
Glama
nextcloud-mcp-server

nextcloud-mcp-server

๏ปฟ

๐ŸŒ NextCloud MCP Server

npm version Downloads License: MIT TypeScript

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


๐Ÿš€ 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


Related MCP server: AIquila MCP Server

๐Ÿ“ฆ Installation

# 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

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

# 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

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"
      }
    }
  }
}
# Run the MCP server
nextcloud-mcp-server

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

๐Ÿ› ๏ธ Available Tools

๐Ÿ“ File Operations

๐Ÿ”— Sharing Operations


๐Ÿ“– Documentation

๐ŸŽฏ Tool Examples

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

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

{
  "name": "upload-file",
  "arguments": {
    "remotePath": "/documents/report.pdf",
    "content": "JVBERi0xLjQK..."  // base64 encoded content
  }
}
{
  "name": "move-file",
  "arguments": {
    "sourcePath": "/old-location/document.pdf",
    "destinationPath": "/new-location/document.pdf",
    "overwrite": false
  }
}

Response: Confirmation message with source and destination paths

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

Response: Confirmation message with copy operation details

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

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

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

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

Response: Confirmation of version restoration

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

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

Contributors Welcome PRs Welcome

  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

๐Ÿ’ก Ways to Contribute


๐Ÿ’– Support

Show Your Support! โญ

If this project helped you, please consider giving it a โญ on GitHub!

GitHub stars GitHub forks

๐Ÿ—ฃ๏ธ Get Help

๐Ÿ”— Connect With Us

GitHub npm


๐Ÿ“œ License

MIT License ยฉ 2024 Abdullah MASHUK

License: MIT

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

๐Ÿ“– Read Full License


๐Ÿ“ˆ Changelog

๐ŸŽ‰ 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 ๐ŸŒ‰

Built with TypeScript Powered by MCP

Available Tools

14 tools
copy-fileB

Copy a file or directory in NextCloud

Inputs: sourcePath (required), destinationPath (required), overwrite.

create-directoryB

Create a new directory in NextCloud

Inputs: path (required).

create-shareB

Create a share link for a file or directory

Inputs: path (required), shareType, shareWith, permissions, +3 more.

delete-fileC

Delete a file or directory from NextCloud

Inputs: path (required).

delete-shareB

Delete an existing share

Inputs: shareId (required).

download-fileB

Download a file from NextCloud

Inputs: path (required).

get-file-versionsB

Get version history of a file

Inputs: path (required).

list-filesC

List files and directories in NextCloud

Inputs: path.

list-sharesC

List existing shares

Inputs: path.

move-fileB

Move or rename a file or directory in NextCloud

Inputs: sourcePath (required), destinationPath (required), overwrite.

restore-file-versionB

Restore a specific version of a file

Inputs: path (required), versionId (required).

search-filesB

Search for files and directories by name or content

Inputs: query (required), path, limit, type.

test-connectionA

Test connection to NextCloud server

Inputs: no named parameters.

upload-fileC

Upload a file to NextCloud

Inputs: remotePath (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.5/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: file operations are separate from sharing, versioning, and connection testing. No two tools overlap in function.

    Naming Consistency5/5

    All tool names follow a consistent verb-noun pattern with hyphens (e.g., copy-file, create-share). No mixing of conventions.

    Tool Count5/5

    14 tools is well-scoped for a NextCloud file management server, covering essential operations without being overwhelming.

    Completeness4/5

    The tool surface covers core CRUD for files, versioning, and sharing. Minor gap: no update-share tool, but sharing is typically create/delete only.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to interact with Nextcloud instances through 30 tools across Notes, Calendar, Contacts, Tables, and WebDAV file operations, featuring a powerful unified search system for finding files without exact paths.
      18 npm
      39
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables Claude to list, read, write, create, delete, and search files on a self-hosted Nextcloud instance via WebDAV, with additional Obsidian vault-aware operations for frontmatter, tags, backlinks, and wikilinks.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to securely access and manage Nextcloud files, edit music tags, and handle archives using the user's own credentials.
      AGPL 3.0

    Appeared in Searches