Nextcloud MCP Server

A production-ready MCP server that connects AI assistants to your Nextcloud instance.

Enable Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language conversations.

This is a dedicated standalone MCP server designed for external MCP clients like Claude Code and IDEs. It runs independently of Nextcloud (Docker, VM, Kubernetes, or local) and provides deep CRUD operations across Nextcloud apps.

[!NOTE] Looking for AI features inside Nextcloud? Nextcloud also provides Context Agent, which powers the Assistant app and runs as an ExApp inside Nextcloud. See docs/comparison-context-agent.md for a detailed comparison of use cases.

[!TIP] Don't want to self-host? Astrolabe Cloud is a managed hosting service for this MCP server, aimed at users and teams who want advanced features like background sync and semantic search without operating the infrastructure themselves. The service is currently under development — sign up on the landing page to join the early-adopter list.

Quick Start

Run the server locally with uvx (no installation required):

NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
NEXTCLOUD_USERNAME=your_username \
NEXTCLOUD_PASSWORD=your_app_password \
  uvx nextcloud-mcp-server run --transport stdio

Or add it directly to your MCP client configuration (e.g. claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "nextcloud": {
      "command": "uvx",
      "args": ["nextcloud-mcp-server", "run", "--transport", "stdio"],
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

[!TIP] Generate an app password in Nextcloud under Settings > Security > Devices & sessions instead of using your login password.

Docker

For full features including semantic search, run with Docker:

docker run -p 127.0.0.1:8000:8000 --rm \
  -e NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
  -e NEXTCLOUD_USERNAME=your_username \
  -e NEXTCLOUD_PASSWORD=your_app_password \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

Then connect your MCP client (Claude Desktop, IDEs, mcp dev, etc.) to http://127.0.0.1:8000/mcp.

For Kubernetes, see cbcoutinho/helm-charts. For other deployment options and Compose profiles, see docs/installation.md.

Key Features

110+ MCP Tools - Comprehensive API coverage across 10 Nextcloud apps
MCP Resources - Structured data URIs for browsing Nextcloud data
Semantic Search (Experimental) - Optional vector-powered search for Notes, Files, News items, Deck cards, and Mail messages (requires Qdrant + Ollama)
Document Processing - OCR and text extraction from PDFs, DOCX, images with progress notifications
Flexible Deployment - Docker, Kubernetes (Helm chart), VM, or local installation
Production-Ready Auth - Basic Auth with app passwords; multi-user via Login Flow v2 — MCP clients authenticate via OAuth, the server handles Nextcloud app passwords transparently
Tag-Based File Exclusion - Hide sensitive files/folders from MCP file tools by tagging them with a configured Nextcloud system tag (EXCLUDED_TAGS). See docs/configuration.md
Multiple Transports - streamable-http (default) and stdio

Supported Apps

App	Tools	Capabilities
Notes	7	Full CRUD, keyword search, semantic search
Calendar	20+	Events, todos (tasks), recurring events, attendees, availability
Contacts	8	Full CardDAV support, address books
Files (WebDAV)	12	Filesystem access, OCR/document processing
Deck	15	Boards, stacks, cards, labels, assignments
Cookbook	13	Recipe management, URL import (schema.org)
Tables	5	Row operations on Nextcloud Tables
Sharing	10+	Create and manage shares
News	8	Feeds, folders, items, feed health monitoring
Mail	5	Read-only: accounts, mailboxes, messages, attachments (via Mail app's OCS API)
Collectives	16	Full CRUD on collectives, pages, and tags
Talk (spreed)	6	List conversations, read/post messages, mark as read, list participants
Semantic Search	2+	Vector search for Notes, Files, News items, Deck cards, and Mail messages (experimental, opt-in, requires infrastructure)

Want to see another Nextcloud app supported? Open an issue or contribute a pull request!

Authentication

The MCP server authenticates to Nextcloud using app-specific passwords (Basic Auth). Three deployment modes are supported:

Mode	Best for
Single-User (BasicAuth)	Personal use, development, single-user deployments
Multi-User (BasicAuth pass-through)	Multi-user setups where clients send credentials via Authorization header
Multi-User (Login Flow v2)	Multi-user / hosted deployments — clients authenticate to the MCP server via OAuth, and the server obtains a per-user app password from Nextcloud and uses it transparently

OAuth-direct-to-Nextcloud is no longer supported (it required upstream patches to user_oidc that were never merged). Login Flow v2 replaces it for multi-user deployments and works with stock Nextcloud.

See docs/authentication.md for setup instructions.

Semantic Search

An experimental RAG pipeline that lets MCP clients find Nextcloud content by meaning rather than keywords — a query for "car" also surfaces notes about "vehicle" or "transportation". Disabled by default (ENABLE_SEMANTIC_SEARCH=false); requires a vector database and embedding service. See docs/semantic-search-architecture.md and docs/configuration.md.

[!TIP] Don't want to run Qdrant and an embedding service? Astrolabe Cloud (under development) provides semantic search and background sync as a managed service.

Documentation

Installation — Docker, Compose profiles, local, VM
Configuration — Environment variables, document processing, semantic search setup
Authentication — Basic Auth, Login Flow v2
Running the Server — Start, manage, troubleshoot
App Documentation — Per-app guides (Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables)
Semantic Search Architecture + Vector Sync UI
Login Flow v2 — recommended multi-user setup (architecture, env vars, scope reference, troubleshooting)
Troubleshooting · Comparison with Context Agent

Contributing

Contributions are welcome!

Report bugs or request features: GitHub Issues
Submit improvements: Pull Requests
Development guidelines: CLAUDE.md

Security

Found a security issue? Do not open a public GitHub issue. Use GitHub's private vulnerability reporting, or email security@astrolabecloud.com if you can't use GitHub. See SECURITY.md for details.

License

This project is licensed under the AGPL-3.0 License. See LICENSE for details.

NextcloudNextcloud