Nextcloud MCP Server

What is Nextcloud MCP Server about?

The server acts as a bridge between LLMs (e.g., GPT, Gemini, Claude) and a Nextcloud instance, exposing tools for creating, reading, updating, and deleting resources within supported Nextcloud apps.

How to use Nextcloud MCP Server?

Configure credentials – create a .env file (or any env file) with NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD.
Run locally – install dependencies with uv sync and start the server:
```
uv run python -m nextcloud_mcp_server.app --host 0.0.0.0 --port 8080
```
Use --enable-app to limit which Nextcloud apps are exposed.

Run with Docker – pull ghcr.io/cbcoutinho/nextcloud-mcp-server and launch:

docker run -p 8000:8000 --env-file .env ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
  --transport streamable-http

Connect an MCP client – e.g., uv run mcp dev (MCP Inspector) to explore tools and resources via a browser.

Key features of Nextcloud MCP Server

Full‑stack support for Notes, Calendar, Files (WebDAV), Contacts, and Deck with CRUD capabilities.
Partial support for Tables (row operations only).
Two transport modes: modern streamable-http (recommended) and legacy SSE.
Selective app enablement via --enable-app to reduce footprint or restrict functionality.
Automatic read‑only resources (e.g., nc://capabilities, notes://settings) for LLM discovery.
Docker image for quick deployment.

Use cases of Nextcloud MCP Server

Automated note taking – LLM drafts, updates, and searches notes based on user prompts.
Smart calendar management – Generate events, set reminders, and handle recurring meetings through natural language.
File operations – Retrieve, create, or modify files without writing code, useful for AI‑driven assistants.
Contact syncing – Keep address books up‑to‑date via conversational commands.
Project management – Manipulate Deck boards, stacks, and cards programmatically.
Custom workflows – Combine multiple app tools to build end‑to‑end automation (e.g., create a note, attach a file, and schedule a calendar event in one LLM call).

FAQ from the Nextcloud MCP Server

Q: Which transport should I use? A: streamable-http is the recommended modern transport. SSE is kept only for backward compatibility.

Q: Can I run the server without Docker? A: Yes. Clone the repo, install Python 3.11+, run uv sync, and start the server with the CLI.

Q: How do I limit the exposed apps? A: Use the --enable-app flag multiple times (e.g., --enable-app notes --enable-app calendar).

Q: Do I need a special Nextcloud account? A: Use any account that has an App Password generated in the Nextcloud security settings. Dedicated app passwords improve security.

Q: Is there support for Tasks? A: Tasks integration is not started yet (tracked in issue #73).

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.

Quick Start

The fastest way to get started is via Smithery - no Docker or self-hosting required:

Visit the Smithery marketplace page
Click "Deploy" and configure:
- Nextcloud URL: Your Nextcloud instance (e.g., https://cloud.example.com)
- Username: Your Nextcloud username
- App Password: Generate one in Nextcloud → Settings → Security → Devices & sessions

[!NOTE] Smithery runs in stateless mode without semantic search. For full features, use Docker or see ADR-016.

Docker (Self-Hosted)

For full features including semantic search, run with Docker:

# 1. Create a minimal configuration
cat > .env << EOF
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password
EOF

# 2. Start the server
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

# 3. Test the connection
curl http://127.0.0.1:8000/health/ready

# 4. Connect to the endpoint
http://127.0.0.1:8000/sse

# Or with --transport streamable-http
http://127.0.0.1:8000/mcp

Next Steps:

Connect your MCP client (Claude Desktop, IDEs, mcp dev, etc.)
See docs/installation.md for other deployment options (local, Kubernetes)

Key Features

90+ MCP Tools - Comprehensive API coverage across 8 Nextcloud apps
MCP Resources - Structured data URIs for browsing Nextcloud data
Semantic Search (Experimental) - Optional vector-powered search for Notes (requires Qdrant + Ollama)
Document Processing - OCR and text extraction from PDFs, DOCX, images with progress notifications
Flexible Deployment - Docker, Kubernetes (Helm), VM, or local installation
Production-Ready Auth - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
Multiple Transports - SSE, HTTP, and streamable-http support

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
Semantic Search	2+	Vector search for Notes (experimental, opt-in, requires infrastructure)

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

Authentication

[!IMPORTANT] OAuth2/OIDC is experimental and requires a manual patch to the user_oidc app:

Required patch: Bearer token support (issue #1221)

Impact: Without the patch, most app-specific APIs fail with 401 errors

Recommendation: Use Basic Auth for production until upstream patches are merged

See docs/oauth-upstream-status.md for patch status and workarounds.

Recommended: Basic Auth with app-specific passwords provides secure, production-ready authentication. See docs/authentication.md for setup details and OAuth configuration.

Authentication Modes

The server supports two authentication modes:

Single-User Mode (BasicAuth):

One set of credentials shared by all MCP clients
Simple setup: username + app password in environment variables
All clients access Nextcloud as the same user
Best for: Personal use, development, single-user deployments

Multi-User Mode (OAuth):

Each MCP client authenticates separately with their own Nextcloud account
Per-user scopes and permissions (clients only see tools they're authorized for)
More secure: tokens expire, credentials never shared with server
Best for: Teams, multi-user deployments, production environments with multiple users

See docs/authentication.md for detailed setup instructions.

Semantic Search

The server provides an experimental RAG pipeline to enable Semantic Search that enables MCP clients to find information in Nextcloud based on meaning rather than just keywords. Instead of matching "machine learning" only when those exact words appear, it understands that "neural networks," "AI models," and "deep learning" are semantically related concepts.

Example:

Keyword search: Query "car" only finds notes containing "car"
Semantic search: Query "car" also finds notes about "automobile," "vehicle," "sedan," "transportation"

This enables natural language queries and helps discover related content across your Nextcloud notes.

[!NOTE] Semantic Search is experimental and opt-in:

Disabled by default (VECTOR_SYNC_ENABLED=false)

Currently supports Notes app only (multi-app support planned)

Requires additional infrastructure: vector database + embedding service

Answer generation (nc_semantic_search_answer) requires MCP client sampling support

See docs/semantic-search-architecture.md for architecture details and docs/configuration.md for setup instructions.

Documentation

Getting Started

Installation - Docker, Kubernetes, local, or VM deployment
Configuration - Environment variables and advanced options
Authentication - Basic Auth vs OAuth2/OIDC setup
Running the Server - Start, manage, and troubleshoot

Features

App Documentation - Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables
Document Processing - OCR and text extraction setup
Semantic Search Architecture - Experimental vector search (Notes only, opt-in)
Vector Sync UI Guide - Browser interface for semantic search visualization and testing

Advanced Topics

OAuth Architecture - How OAuth works (experimental)
OAuth Quick Start - 5-minute OAuth setup
OAuth Setup Guide - Detailed OAuth configuration
Troubleshooting - Common issues and solutions
Comparison with Context Agent - When to use each approach

Examples

Create a Note

AI: "Create a note called 'Meeting Notes' with today's agenda"
→ Uses nc_notes_create_note tool

Import Recipes

AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction

Schedule Meetings

AI: "Schedule a team meeting for next Tuesday at 2pm"
→ Uses nc_calendar_create_event tool

Manage Files

AI: "Create a folder called 'Project X' and move all PDFs there"
→ Uses nc_webdav_create_directory and nc_webdav_move tools

Semantic Search (Experimental, Opt-in)

AI: "Find notes related to machine learning concepts"
→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)

Note: For AI-generated answers with citations, use nc_semantic_search_answer (requires MCP client with sampling support).

Contributing

Contributions are welcome!

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

Security

This project takes security seriously:

Production-ready Basic Auth with app-specific passwords
OAuth2/OIDC support (experimental, requires upstream patches)
Per-user access tokens
No credential storage in OAuth mode
Regular security assessments

Nextcloud MCP Server