nextcloud-mcp

Twine2546/nextcloud-mcp

3.1

If you are the rightful owner of nextcloud-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that integrates with Nextcloud's WebDAV and OCS APIs for AI assistant interaction.

Nextcloud MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Nextcloud's WebDAV and OCS APIs, enabling AI assistants to interact with your Nextcloud instance.

Features

File Operations (WebDAV)

  • list_files: List files and folders in any directory
  • download_file: Download and read file contents
  • upload_file: Upload files (text or binary via base64)
  • delete_item: Delete files or folders
  • create_folder: Create new folders
  • move_item: Move or rename files and folders
  • get_file_info: Get detailed metadata about files/folders
  • search_files: Search for files and folders by name

Sharing Operations (OCS API)

  • create_share: Create public share links with optional password protection
  • list_shares: List all shares or shares for a specific path
  • delete_share: Remove existing shares

Installation

You can run this MCP server either natively with Node.js or in a Docker container.

Option 1: Docker (Recommended)

Prerequisites:

  • Docker Engine 20.10+
  • Docker Compose v2+
  • Dockge (optional, for web UI)

Quick Start:

# 1. Configure your credentials
cp .env.example .env
nano .env  # Add your Nextcloud password

# 2. Start with Docker Compose
./docker-start.sh

# Or manually:
docker compose up -d

# 3. Test the container
./docker-test.sh

For detailed Docker instructions, see

Option 2: Native Node.js

Prerequisites:

  • Node.js 18 or higher
  • A Nextcloud instance (tested with Nextcloud 32)
  • Nextcloud user credentials or app password

Setup:

  1. Clone or download this repository:
cd /config/projects/programming/mcps/nextcloud
  1. Install dependencies:
npm install
  1. Build the TypeScript code:
npm run build
  1. Configure environment variables (see Configuration section below)

Configuration

The server requires three environment variables:

  • NEXTCLOUD_URL: Your Nextcloud instance URL (e.g., http://192.168.1.138:8666)
  • NEXTCLOUD_USERNAME: Your Nextcloud username (e.g., Daniel)
  • NEXTCLOUD_PASSWORD: Your Nextcloud password or app password

Creating an App Password (Recommended)

For better security, use an app password instead of your main password:

  1. Log in to your Nextcloud instance
  2. Go to Settings → Security
  3. Scroll to "Devices & sessions"
  4. Enter a name for the app (e.g., "MCP Server")
  5. Click "Create new app password"
  6. Copy the generated password and use it as NEXTCLOUD_PASSWORD

MCP Client Configuration

For Claude Code (SSE Proxy)

This is the recommended setup for Claude Code integration with MCP suites.

Add this to your Claude Code configuration file (~/.claude.json or similar):

{
  "mcpServers": {
    "nextcloud": {
      "type": "sse",
      "url": "http://nextcloud-mcp-proxy:3009/sse"
    }
  }
}

SSE Proxy Setup: The SSE proxy allows Claude Code to connect to the MCP server via Server-Sent Events. Deploy with:

# On your Docker host
docker run -d \
  --name nextcloud-mcp-proxy \
  --network mcp_network \
  -p 3009:3009 \
  -v /path/to/nextcloud:/app/nextcloud-mcp:ro \
  --restart unless-stopped \
  python:3.11-slim \
  sh -c '
    apt-get update > /dev/null 2>&1 &&
    apt-get install -y nodejs npm > /dev/null 2>&1 &&
    pip install --no-cache-dir mcp-proxy > /dev/null 2>&1 &&
    exec mcp-proxy --port 3009 --host 0.0.0.0 -- sh /app/nextcloud-mcp/start-mcp.sh
  '

Create a wrapper script (start-mcp.sh in the project root) with your credentials:

#!/bin/sh
export NEXTCLOUD_URL='http://your-nextcloud:8666'
export NEXTCLOUD_USERNAME='your-username'
export NEXTCLOUD_PASSWORD='your-password'
exec node /app/nextcloud-mcp/build/index.js
For Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Docker (if using Docker container):

{
  "mcpServers": {
    "nextcloud": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "nextcloud-mcp",
        "node",
        "build/index.js"
      ]
    }
  }
}

Note: Container must be running first. See for details.

Option B: Native Node.js:

{
  "mcpServers": {
    "nextcloud": {
      "command": "node",
      "args": ["/config/projects/programming/mcps/nextcloud/build/index.js"],
      "env": {
        "NEXTCLOUD_URL": "http://192.168.1.138:8666",
        "NEXTCLOUD_USERNAME": "Daniel",
        "NEXTCLOUD_PASSWORD": "your-password-or-app-password-here"
      }
    }
  }
}
For Other MCP Clients

Native Node.js:

  • Command: node
  • Args: ["/config/projects/programming/mcps/nextcloud/build/index.js"]
  • Environment variables: As listed above

Docker:

  • Command: docker
  • Args: ["exec", "-i", "nextcloud-mcp", "node", "build/index.js"]
  • Environment variables: Configured in docker-compose.yml/.env

Usage Examples

Once configured, you can ask your AI assistant to interact with Nextcloud:

File Management

  • "List all files in my Documents folder"
  • "Download the file at /Documents/report.txt"
  • "Upload this content to /Documents/notes.txt"
  • "Create a folder called /Projects/NewProject"
  • "Move /temp/file.pdf to /Archive/file.pdf"
  • "Delete /temp/old_file.txt"

Searching

  • "Search for all PDF files"
  • "Find files with 'meeting' in the name"

Sharing

  • "Create a public share link for /Photos/vacation.jpg"
  • "Create a password-protected share for /Documents/confidential.pdf with password 'secret123'"
  • "List all my active shares"
  • "Delete share with ID 12345"

API Tools Reference

list_files

Lists files and folders in a directory.

Parameters:

  • path (optional): Directory path, defaults to root /

Example:

{
  "path": "/Documents"
}

download_file

Downloads and returns file contents.

Parameters:

  • path (required): File path

Example:

{
  "path": "/Documents/report.txt"
}

upload_file

Uploads a file to Nextcloud.

Parameters:

  • path (required): Destination path
  • content (required): File content
  • encoding (optional): "text" or "base64", defaults to "text"

Example:

{
  "path": "/Documents/new_file.txt",
  "content": "Hello, Nextcloud!",
  "encoding": "text"
}

create_share

Creates a share link for a file or folder.

Parameters:

  • path (required): Path to share
  • shareType (optional): 0=user, 1=group, 3=public link (default)
  • permissions (optional): 1=read, 2=update, 4=create, 8=delete, 16=share, 31=all (default: 1)
  • password (optional): Password protection for the share

Example:

{
  "path": "/Photos/image.jpg",
  "shareType": 3,
  "permissions": 1,
  "password": "mypassword"
}

System Information

Discovered Nextcloud Instance:

Development

Build

npm run build

Watch mode (auto-rebuild on changes)

npm run watch

Start manually

npm start

Troubleshooting

"Missing required environment variables"

Ensure all three environment variables are set in your MCP client configuration.

Authentication failures

  • Verify your username and password are correct
  • If using app password, ensure it was copied correctly
  • Check that your Nextcloud instance is accessible from your machine

"Cannot write into config directory"

This is a Nextcloud permission issue. The MCP server doesn't need write access to config, so this shouldn't affect functionality.

Connection errors

  • Verify the Nextcloud URL is correct and accessible
  • Check if Nextcloud is in maintenance mode (maintenance: true in config.php)
  • Ensure port 8666 is accessible from your machine

Security Notes

  • Store credentials securely in your MCP client configuration
  • Use app passwords instead of main account passwords
  • Limit MCP server access to trusted AI assistants only
  • Review share links and permissions regularly

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.