MCP Nextcloud

🚀 Nextcloud MCP Server

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

🚀 Quick Start

This project is a complete rewrite in TypeScript of the original Python-based cbcoutinho/nextcloud-mcp-server, now with Smithery deployment support for one-click cloud deployment.

⚠️ Important Note

This project is a rewrite of the original Python-based project, with significant differences in language, support, structure, dependencies, and deployment.

💡 Usage Tip

For a quick start, you can install the project via npm and run it as an MCP server.

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

📦 Installation

Prerequisites

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

Quick Start with npm (Recommended)

# Install globally
npm install -g mcp-nextcloud

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

💻 Usage Examples

Basic Usage

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

Advanced Usage

// 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
});

📚 Documentation

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

✨ 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

🔧 Technical Details

Configuration

Environment Variables

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

# .env
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password_or_login_password

Important Security Note: Use a dedicated Nextcloud App Password instead of your regular login password. Generate one in your Nextcloud Security settings.

Smithery Configuration

When deploying via Smithery, you can configure credentials through:

• Environment variables (as above)
• Smithery configuration interface (recommended for cloud deployment)

Deployment & Usage

Option 1: npm Package (Recommended for End Users)

npm install -g mcp-nextcloud
mcp-nextcloud

Option 2: Local Development with Smithery Playground

npm run dev

Option 3: Cloud Deployment via Smithery

npm run build
npm run deploy

Manual Local Development

npm run start

Publishing to npm

For Maintainers

npm run build
npm version patch|minor|major
npm publish
npm view mcp-nextcloud

Publishing Checklist

• [ ] All tests pass (Smithery deployment confirmed working)
• [ ] TypeScript builds without errors (npm run build)
• [ ] Version bumped appropriately (npm version)
• [ ] README updated with changes
• [ ] .npmignore properly excludes development files
• [ ] CLI executable works (dist/cli.js)

Dual Deployment Strategy

This project supports both deployment methods simultaneously:

• Smithery: For cloud deployment and development testing
• npm: For end-user installation and MCP client integration

Smithery Integration

This project includes full Smithery support with:

• smithery.yaml: Specifies TypeScript runtime
• Development server: Local testing with hot reload
• One-click deployment: Deploy to cloud with a single command
• Configuration management: Secure credential handling
• Playground integration: Immediate testing interface

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Acknowledgments

• Original Python implementation by cbcoutinho
• Built with Model Context Protocol
• Deployable via Smithery