hithereiamaliff-mcp-nextcloud

Nextcloud MCP Server

MCP Endpoint: https://mcp.techmavie.digital/nextcloud/mcp

Note: This project is a complete rewrite in TypeScript of the original Python-based cbcoutinho/nextcloud-mcp-server, now with self-hosted VPS deployment and Smithery deployment support.

Key Differences from the Original Repository:

• Language: This project is written in TypeScript, while the original is in Python.
• Smithery Support: Added full support for Smithery deployment and local testing via Smithery playground.
• Project Structure: The project structure has been adapted for a Node.js/TypeScript environment with MCP SDK integration.
• Dependencies: This project uses npm for package management, whereas the original uses Python's dependency management tools.
• Deployment: Now supports both local development and cloud deployment via Smithery.

The Nextcloud MCP (Model Context Protocol) server allows Large Language Models (LLMs) like OpenAI's GPT, Google's Gemini, or Anthropic's Claude to interact with your Nextcloud instance. This enables automation of various Nextcloud actions across Notes, Calendar, Contacts, Tables, and WebDAV file operations.

The hosted HTTP integration now supports a safer multi-user flow through the MCP Key Service. Instead of embedding raw Nextcloud credentials in the connector URL, hosted clients can use a user-scoped usr_... key and let the server resolve credentials server-side.

Features

The server provides integration with multiple Nextcloud apps, enabling LLMs to interact with your Nextcloud data through a comprehensive set of 30 tools across 5 main categories.

Supported Nextcloud Apps

Available Tools (30 Total)

📝 Notes Tools (5 tools)

📅 Calendar Tools (6 tools)

👥 Contacts Tools (6 tools)

📊 Tables Tools (6 tools)

📁 WebDAV File System Tools (6 tools)

🔍 Revolutionary Unified WebDAV Search Feature

The crown jewel of this MCP server is the powerful unified search system for WebDAV files, inspired by modern search interfaces like on an another MCP that I have created: mcp-datagovmy. This completely transforms how you interact with your Nextcloud files by eliminating the need to specify exact file paths.

✨ Key Features

• 🎯 Multi-scope Search: Search across filenames, file content, and metadata simultaneously
• 🧠 Smart File Type Detection: Automatically handles text files, code, configuration files, documents, and media
• 🔧 Advanced Filtering: Filter by file type, size range, modification date, and directory
• 📈 Intelligent Ranking: Results ranked by relevance with bonuses for recent files and exact matches
• 👀 Content Preview: Optional content previews for matched text files
• ⚡ Performance Optimized: Intelligent caching, timeout protection, and parallel processing
• 🛡️ Error Recovery: Fallback strategies prevent timeouts and provide helpful suggestions

🚀 Usage Examples

// Basic search - find all files containing "FAQ Dean List"
await nextcloud_webdav_search_files({
  query: "FAQ Dean List"
});

// Advanced search - find PDF reports from 2024
await nextcloud_webdav_search_files({
  query: "report 2024",
  fileTypes: ["pdf"],
  searchIn: ["filename", "content"],
  limit: 20,
  includeContent: true,
  quickSearch: true
});

// Directory-specific search with date range
await nextcloud_webdav_search_files({
  query: "meeting notes",
  basePath: "/Documents",
  searchIn: ["filename", "content"],
  dateRange: {
    from: "2024-01-01",
    to: "2024-12-31"
  }
});

// Search by file characteristics
await nextcloud_webdav_search_files({
  query: "configuration files",
  sizeRange: { min: 1024, max: 102400 }, // 1KB - 100KB
  fileTypes: ["json", "yaml", "xml", "conf"]
});

// Quick search for large directories (optimized)
await nextcloud_webdav_search_files({
  query: "budget",
  basePath: "/", // Root directory
  quickSearch: true, // Enables optimizations
  limit: 25,
  maxDepth: 2 // Limit search depth
});

📋 Complete Parameter Reference

🎯 Performance Tips

• For root directory searches: Use quickSearch: true and maxDepth: 2-3 for faster results
• For specific directories: Use basePath: "/Documents" instead of searching root "/"
• For large result sets: Add fileTypes filter to narrow scope
• For timeout issues: Enable quickSearch and use smaller limit values

🧪 Test Tool (1 tool)

🔄 Before vs After: The Search Revolution

Before Unified Search

// You had to know exact paths
await nextcloud_webdav_read_file({
  path: "/Documents/Finance/Reports/Q4_Budget_Analysis_2024.pdf"
});

// Multiple calls needed to explore
await nextcloud_webdav_list_directory({ path: "/" });
await nextcloud_webdav_list_directory({ path: "/Documents" });
await nextcloud_webdav_list_directory({ path: "/Documents/Finance" });
// ... and so on

After Unified Search ✨

// Natural language search across entire Nextcloud!
await nextcloud_webdav_search_files({
  query: "Q4 budget analysis 2024",
  fileTypes: ["pdf"]
});

// Finds files instantly regardless of location!

🛠️ Advanced Search Strategies

Content-Aware Search

The system intelligently extracts and searches content from:

• 📝 Text Files: .txt, .md, .csv - Full content indexing
• 💻 Code Files: .js, .ts, .py, .html, .css - Syntax-aware search
• ⚙️ Config Files: .json, .xml, .yaml - Structure-aware indexing
• 📄 Documents: .pdf, .docx - Metadata and properties
• 🎬 Media Files: Images, videos - EXIF data and metadata

Smart Ranking System

Results are ranked using advanced algorithms:

1. Exact filename matches → 100 points
2. Word boundaries in filenames → 80 points
3. Partial filename matches → 60+ points (position bonus)
4. Content frequency matches → 50+ points (term density)
5. Recent file bonus → +10 points (last 30 days)
6. File type preference → +5 points (text/code files)
7. Size convenience → +5 points (files under 100KB)

Error Handling & Recovery

• 🕐 20-second timeout protection - Prevents hanging operations
• 🔄 Automatic fallback search - Falls back to directory listing if indexing fails
• 💡 Intelligent suggestions - Provides helpful tips for optimization
• 📊 Performance metrics - Shows search duration and result counts

Installation

Quick Start with npm (Recommended)

Install directly from npm and run as an MCP server:

# Install globally
npm install -g mcp-nextcloud

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

Usage as MCP Server

After installation, you can run the MCP server directly:

# If installed globally
mcp-nextcloud

# If installed locally
npx mcp-nextcloud

# Or using npm script
npm exec mcp-nextcloud

Environment Setup: Create a .env file with your Nextcloud credentials:

NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

Integration with LLM Applications

Add to your MCP client configuration (e.g., Claude Desktop, Continue, etc.):

For CLI mode (local, single-user):

{
  "mcpServers": {
    "nextcloud": {
      "command": "mcp-nextcloud",
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

For hosted HTTP mode (via MCP Key Service):

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX"
    }
  }
}

Recommended for hosted clients: Use the path-based URL form (/mcp/usr_...) for Claude.ai and similar hosted connectors. Keep the query-param form as a compatibility option for inspectors and clients that preserve query params reliably.

For self-hosted HTTP mode (your own server):

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp",
      "headers": {
        "X-API-Key": "your-server-api-key",
        "X-Nextcloud-Host": "https://your.nextcloud.instance.com",
        "X-Nextcloud-Username": "your_username",
        "X-Nextcloud-Password": "your_app_password"
      }
    }
  }
}

Prerequisites

• Node.js 18+
• Access to a Nextcloud instance
• npm or yarn package manager

Local Development Setup

1. Clone the repository:

   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
   cd mcp-nextcloud
   

2. Install dependencies:

   npm install
   

3. Configure your Nextcloud credentials (see Configuration section)

4. Build the project:

   npm run build
   

Configuration

Environment Variables

Create a .env file in the root directory based on .env.sample:

# --- CLI/stdio mode only ---
# These are used when running the server in CLI mode (npm run dev, npm run cli).
# They are NOT used by the HTTP server.
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

# --- HTTP server: Self-Hosted mode ---
# Required for self-hosted /mcp auth, and also used for /analytics access.
MCP_API_KEY=your-secret-api-key-here

# --- HTTP server: Key Service mode ---
# Set both to enable user api_key=usr_... resolution via the MCP Key Service.
# Users obtain and manage those keys at https://mcpkeys.techmavie.digital
# The MCP server itself talks to the resolver endpoint below.
KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve
KEY_SERVICE_TOKEN=your-key-service-bearer-token

# Optional: Comma-separated list of allowed CORS origins.
ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai

# Optional diagnostics for remote MCP debugging.
# These are intended for temporary troubleshooting in hosted HTTP mode.
MCP_TRACE_HTTP=false
ENABLE_MCP_DIAGNOSTICS=false

# Optional dedicated endpoint for Smithery URL publishing.
ENABLE_SMITHERY_ENDPOINT=false

Important Security Notes:

• Use a dedicated Nextcloud App Password instead of your regular login password. Generate one in your Nextcloud Security settings.
• In HTTP mode, NEXTCLOUD_* environment variables are never used. Self-hosted clients provide credentials via X-Nextcloud-* headers, while key-service clients send only a usr_... key.
• Generate a strong API key: openssl rand -hex 32

Smithery Configuration

When deploying via Smithery, you can configure credentials through:

• Smithery's configuration interface for URL-published servers

For Smithery, the recommended model is:

• users enter nextcloudHost, nextcloudUsername, and nextcloudPassword directly
• Smithery forwards those values to the dedicated /smithery/mcp endpoint as headers
• the hosted usr_... key-service flow remains separate and continues to use /mcp/usr_...

Deployment & Usage

Option 1: Hosted Server (Recommended)

The easiest way to use this MCP server is via the hosted endpoint. No installation required!

Endpoint: https://mcp.techmavie.digital/nextcloud/mcp

Authentication

The hosted server uses the MCP Key Service for authentication. You get a personal API key (usr_XXXXXXXX) from the MCP Key Service portal:

https://mcpkeys.techmavie.digital

The server then resolves your Nextcloud credentials automatically through the resolver endpoint behind the scenes.

Why this is safer than the old query-credential approach:

• raw Nextcloud credentials are not embedded in the connector URL
• revoking a usr_... key is easier than rotating a user's underlying Nextcloud password everywhere
• server-side auditing and policy are easier to centralize
• support/debug workflows are safer because users share a scoped key, not their real Nextcloud password

Claude.ai / hosted connector URL (recommended):

https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX

Alternative URL for clients that preserve query params correctly:

https://mcp.techmavie.digital/nextcloud/mcp?api_key=usr_XXXXXXXX

Client Configuration

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX"
    }
  }
}

Test with MCP Inspector

npx @modelcontextprotocol/inspector
# Select "Streamable HTTP"
# Enter URL: https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX

Option 2: Self-Hosted (VPS)

If you prefer to run your own instance, the built-in Docker + Nginx setup is:

# Set required environment variables
export MCP_API_KEY=your-secret-api-key  # Required for self-hosted /mcp auth and /analytics
export KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve  # Optional: enables key service mode
export KEY_SERVICE_TOKEN=your-key-service-bearer-token                      # Optional: enables key service mode

# Using Docker
docker compose up -d --build

# Or run directly
npm run build
npm run start:http

Recommended VPS setup

1. Clone the repo onto your server:

   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
   cd mcp-nextcloud
   

2. Create a .env file with your server settings:

   MCP_API_KEY=your-secret-api-key
   KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve
   KEY_SERVICE_TOKEN=your-key-service-bearer-token
   ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai
   ENABLE_SMITHERY_ENDPOINT=false
   

   Notes:
   • Use KEY_SERVICE_URL + KEY_SERVICE_TOKEN only if you want hosted-style usr_... key resolution.
   • Users obtain and manage those keys at https://mcpkeys.techmavie.digital.
   • The MCP server itself should keep using the resolver endpoint path, not the portal homepage.
   • Set ENABLE_SMITHERY_ENDPOINT=true only if you want to publish the dedicated Smithery direct-credentials endpoint.
3. Start the container:

   docker compose up -d --build
   

4. Add the reverse proxy config from deploy/nginx-mcp.conf to your nginx server block.
5. Validate and reload nginx:

   sudo nginx -t
   sudo systemctl reload nginx
   

6. Verify the server:

   curl http://127.0.0.1:8080/health
   

Important: The HTTP server does NOT use NEXTCLOUD_* environment variables. In self-hosted mode, each client must provide Nextcloud credentials via request headers. In key-service mode, clients send only api_key=usr_....

Remote MCP note: For hosted connectors such as Claude.ai, prefer the path-based URL form (/mcp/usr_...). Keep the query-param form as a compatibility option for inspectors and clients that preserve query params reliably.

Debugging note: If a hosted client shows a generic auth prompt, it does not automatically mean OAuth is required. First verify the auth-free diagnostics route, the key-service resolver response,