This project provides a production-ready, standalone MCP (Model Context Protocol) server that bridges AI assistants like Claude, GPT, and Gemini with Nextcloud instances. It enables users to interact with their Nextcloud data—including notes, calendars, contacts, and files—through natural language conversations, offering deep CRUD operations via a secure API. The server is designed for external MCP clients and runs independently of Nextcloud, making it suitable for various deployment environments.

How It Works

The Nextcloud MCP Server acts as an intermediary, translating natural language requests from AI assistants into structured API calls for Nextcloud. It leverages Nextcloud's app password authentication for secure access and provides a comprehensive set of over 110 MCP tools, offering deep integration with more than 10 Nextcloud applications. Its architecture supports flexible deployment options, including Docker, Kubernetes, VMs, or local setups, and features an optional, experimental RAG pipeline for semantic search capabilities.

Quick Start & Requirements

• Primary install/run:
  • Locally via uvx: NEXTCLOUD_HOST=... NEXTCLOUD_USERNAME=... NEXTCLOUD_PASSWORD=... uvx nextcloud-mcp-server run --transport stdio
  • Docker: docker run -p 127.0.0.1:8000:8000 --rm -e NEXTCLOUD_HOST=... -e NEXTCLOUD_USERNAME=... -e NEXTCLOUD_PASSWORD=... ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
• Prerequisites: A Nextcloud instance, a Nextcloud app password (recommended over login password), Docker (for full features), and optionally Qdrant + Ollama for semantic search.
• Links: Documentation is available for installation, configuration, authentication, semantic search, and comparison with Nextcloud's Context Agent. A managed hosting service, Astrolabe Cloud, is under development.

Highlighted Details

• 110+ MCP Tools: Comprehensive API coverage across 10+ Nextcloud apps including Notes, Calendar, Contacts, Files (WebDAV), Deck, Cookbook, and Talk.
• Semantic Search (Experimental): Optional RAG pipeline for vector-powered search across Notes, Files, News, and Deck items, requiring external vector database and embedding services.
• Flexible Deployment: Supports Docker, Kubernetes (via Helm chart), VM, or local installations.
• Production-Ready Auth: Offers Basic Auth with app passwords and multi-user support via Login Flow v2 (OAuth).
• Document Processing: Includes OCR and text extraction for PDFs, DOCX, and images with progress notifications.
• Tag-Based File Exclusion: Allows sensitive files/folders to be hidden from MCP tools using a configured Nextcloud system tag.

Maintenance & Community

Contributions are welcomed via GitHub Issues for bugs/features and Pull Requests for improvements. Security issues should be reported privately. No specific community channels like Discord or Slack are listed, but GitHub serves as the primary interaction point. Astrolabe Cloud is mentioned as a future managed service.

Licensing & Compatibility

This project is licensed under the AGPL-3.0 License. This strong copyleft license may have implications for commercial use or integration into closed-source projects. Direct OAuth authentication to Nextcloud is no longer supported; Login Flow v2 is the recommended alternative for multi-user deployments.

Limitations & Caveats

Semantic search functionality is experimental and requires significant external infrastructure setup. The AGPL-3.0 license necessitates careful consideration for derivative works and distribution. The managed Astrolabe Cloud service is still under development.