Nextcloud MCP Server

Enable AI assistants to interact with your Nextcloud instance.

The Nextcloud MCP (Model Context Protocol) server allows 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.

High-level Comparison: Nextcloud MCP Server vs. Nextcloud AI Stack

See our detailed comparison for architecture diagrams, workflow examples, and guidance on when to use each approach.

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

Authentication

OAuth2/OIDC provides secure, per-user authentication with access tokens. See Authentication Guide for details.

Quick Start

1. Install

See Installation Guide for detailed instructions, or Helm Chart README for Kubernetes deployment.

2. Configure

Create a .env file:

For Basic Auth (recommended for most users):

For OAuth (experimental - requires patches):

See Configuration Guide for all options.

3. Set Up Authentication

Basic Auth Setup (recommended):

1. Create an app password in Nextcloud (Settings → Security → Devices & sessions)

2. Add credentials to .env file

3. Start the server

OAuth Setup (experimental):

1. Install Nextcloud OIDC apps (oidc v1.10.0+ + user_oidc)

2. Apply required patch to user_oidc app for Bearer token support (see OAuth Upstream Status)

3. Enable dynamic client registration or create an OIDC client with id & secret

4. Configure Bearer token validation in user_oidc

5. Start the server

See OAuth Quick Start for 5-minute setup or OAuth Setup Guide for detailed instructions.

4. Run the Server

The server starts on http://127.0.0.1:8000 by default.

See Running the Server for more options.

5. Connect an MCP Client

Test with MCP Inspector:

Or connect from:

• Claude Desktop

• Any MCP-compatible client

Documentation

Getting Started

• Installation - Install the server

• Configuration - Environment variables and settings

• Authentication - OAuth vs BasicAuth

• Running the Server - Start and manage the server

Architecture

• Comparison with Context Agent - How this MCP server differs from Nextcloud's Context Agent

OAuth Documentation (Experimental)

• OAuth Quick Start - 5-minute setup guide

• OAuth Setup Guide - Detailed setup instructions

• OAuth Architecture - How OAuth works

• OAuth Troubleshooting - OAuth-specific issues

• Upstream Status - Required patches and PRs ⚠️

Reference

• Troubleshooting - Common issues and solutions

App-Specific Documentation

• Notes API

• Calendar (CalDAV)

• Contacts (CardDAV)

• Cookbook

• Deck

• Tables

• WebDAV

MCP Tools & Resources

The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).

Tools

The server provides 90+ tools across 8 Nextcloud apps. When using OAuth, tools are dynamically filtered based on your granted scopes.

For a complete list of all supported OAuth scopes and their descriptions, see OAuth Scopes Documentation.

Available Tool Categories

Document Processing (Optional)

The WebDAV file reading tool (nc_webdav_read_file) supports automatic text extraction from documents and images:

Supported Formats:

• Documents: PDF, DOCX, PPTX, XLSX, RTF, ODT, EPUB

• Images: PNG, JPEG, TIFF, BMP (with OCR)

• Email: EML, MSG files

Features:

• Progress Notifications: Long-running OCR operations (up to 120s) send progress updates every 10 seconds to prevent client timeouts

• Pluggable Architecture: Multiple processor backends (Unstructured.io, Tesseract, custom HTTP APIs)

• Automatic Detection: Files are processed based on MIME type

• Graceful Fallback: Returns base64-encoded content if processing fails

Configuration:

Example Usage:

See env.sample for complete configuration options.

Example Tools:

• nc_notes_create_note - Create a new note

• nc_cookbook_import_recipe - Import recipes from URLs with schema.org metadata

• deck_create_card - Create a Deck card

• nc_calendar_create_event - Create a calendar event

• nc_calendar_create_todo - Create a CalDAV task/todo

• nc_contacts_create_contact - Create a contact

• nc_webdav_upload_file - Upload a file to Nextcloud

• And 80+ more...

Resources

Resources provide read-only access to Nextcloud data:

• nc://capabilities - Server capabilities

• cookbook://version - Cookbook app version info

• nc://Deck/boards/{board_id} - Deck board data

• notes://settings - Notes app settings

• And more...

Run uv run nextcloud-mcp-server --help to see all available options.

Examples

Create a Note

Manage Recipes

Manage Calendar

Organize Files

Project Management

Transport Protocols

The server supports multiple MCP transport protocols:

• streamable-http (recommended) - Modern streaming protocol

• sse (default, deprecated) - Server-Sent Events for backward compatibility

• http - Standard HTTP protocol

Contributing

Contributions are welcome!

• Report bugs or request features: GitHub Issues

• Submit improvements: Pull Requests

• Read CLAUDE.md for development guidelines

Security

This project takes security seriously:

• OAuth2/OIDC support (experimental - requires upstream patches)

• Basic Auth with app-specific passwords (recommended)

• No credential storage with OAuth mode

• Per-user access tokens

• Regular security assessments

Found a security issue? Please report it privately to the maintainers.

License

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

Star History

References

• Model Context Protocol

• MCP Python SDK

• Nextcloud