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.

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

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

# 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.

Create a .env file:

# Copy the sample
cp env.sample .env

For Basic Auth (recommended for most users):

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

For OAuth (experimental - requires patches):

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

See Configuration Guide for all options.

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 + user_oidc)
2. Apply required patches to user_oidc app (see OAuth Upstream Status)
3. Enable dynamic client registration
4. Configure Bearer token validation
5. Start the server

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

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

# Start with Basic Auth (default)
uv run nextcloud-mcp-server

# Or start with OAuth (experimental - requires patches)
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

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

See Running the Server for more options.

Test with MCP Inspector:

uv run mcp dev

Or connect from:

• Claude Desktop
• Any MCP-compatible client

• Installation - Install the server
• Configuration - Environment variables and settings
• Authentication - OAuth vs BasicAuth
• Running the Server - Start and manage the server

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

• 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 ⚠️

• Troubleshooting - Common issues and solutions

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

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

Tools enable AI assistants to perform actions:

• 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_contacts_create_contact - Create a contact
• And many more...

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.

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

AI: "Import the recipe from this URL: https://www.example.com/recipe/chocolate-cake"
→ Uses nc_cookbook_import_recipe tool to extract schema.org metadata

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

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

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

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

Contributions are welcome!

• Report bugs or request features: GitHub Issues
• Submit improvements: Pull Requests
• Read CLAUDE.md for development guidelines

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.

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

• Model Context Protocol
• MCP Python SDK
• Nextcloud