nextcloud-mcp-server/README.md

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.

Features

Supported Nextcloud Apps

App	Support	Features
Notes	✅ Full	Create, read, update, delete, search notes. Handle attachments.
Calendar	✅ Full	Manage events, recurring events, reminders, attendees via CalDAV.
Contacts	✅ Full	CRUD operations for contacts and address books via CardDAV.
Files (WebDAV)	✅ Full	Complete file system access - browse, read, write, organize files.
Deck	✅ Full	Project management - boards, stacks, cards, labels, assignments.
Tables	⚠️ Partial	Row-level operations. Table management not yet supported.
Tasks	❌ Planned	Issue #73

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

Authentication

Mode	Security	Best For
OAuth2/OIDC ✅	🔒 High	Production, multi-user deployments
Basic Auth ⚠️	Lower	Development, testing

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

Quick Start

1. Install

# Clone the repository
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
cd nextcloud-mcp-server

# Install with uv (recommended)
uv sync

# Or using Docker
docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

See Installation Guide for detailed instructions.

2. Configure

Create a .env file:

# Copy the sample
cp env.sample .env

For OAuth (recommended):

NEXTCLOUD_HOST=https://your.nextcloud.instance.com

For Basic Auth:

NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_password

See Configuration Guide for all options.

3. Set Up Authentication

OAuth Setup (recommended):

1. Install Nextcloud OIDC app
2. Enable dynamic client registration
3. Start the server

See OAuth Setup Guide for step-by-step instructions.

4. Run the Server

# Load environment variables
export $(grep -v '^#' .env | xargs)

# Start the server
uv run nextcloud-mcp-server --oauth

# Or with Docker
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

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:

uv run mcp dev

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
• OAuth Setup Guide - Step-by-step OAuth configuration
• Running the Server - Start and manage the server

Reference

• Troubleshooting - Common issues and solutions
• OAuth Bearer Token Issue - Required patch for non-OCS endpoints

App-Specific Documentation

• Notes API
• Calendar (CalDAV)
• Contacts (CardDAV)
• Deck
• Tables
• WebDAV

MCP Tools & Resources

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

Tools

Tools enable AI assistants to perform actions:

• nc_notes_create_note - Create a new note
• deck_create_card - Create a Deck card
• nc_calendar_create_event - Create a calendar event
• nc_contacts_create_contact - Create a contact
• And many more...

Resources

Resources provide read-only access to Nextcloud data:

• nc://capabilities - Server capabilities
• 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

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

Manage Calendar

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

Organize Files

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

Project Management

AI: "Create a new Deck board for Q1 planning with Todo, In Progress, and Done stacks"
→ Uses deck_create_board and deck_create_stack tools

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

# Use streamable-http (recommended)
uv run nextcloud-mcp-server --transport streamable-http

Warning

SSE transport is deprecated and will be removed in a future MCP specification version. Please migrate to streamable-http.

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 for secure authentication
• 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