Nextcloud MCP Server

A Model Context Protocol (MCP) server that exposes Nextcloud functionality as tools for AI assistants. Written in Go for minimal resource usage (~8 MB Docker image on scratch).

Features

• Notes -- create, read, update, delete, search, append
• Deck -- boards, stacks, cards, labels, user assignments
• Talk -- conversations, messages, participants
• Calendar -- events, meetings, availability, bulk operations
• Tasks -- VTODO-based task management
• Files -- WebDAV file operations, search, favorites
• Contacts -- address books, vCard contacts
• Search -- Unified Search across all Nextcloud providers
• Multi-Instance -- manage multiple Nextcloud servers with named configs

Prerequisites

• Go 1.24+ (for building from source)
• A Nextcloud instance with an app password
• Docker (optional, for containerized deployment)

Quick Start

0. Quick Setup (optional)

./setup.sh

This script creates the config directory and walks you through adding your first Nextcloud instance.

1. Build

go build -ldflags="-s -w" -o nextcloud-mcp .

2. Run

./nextcloud-mcp

The server starts on http://0.0.0.0:8080 with the MCP endpoint at POST /mcp.

3. Configure a Nextcloud Instance

Use the nc_config_add_instance tool (via your MCP client) or create the config file manually:

{
  "default_instance": "home",
  "instances": {
    "home": {
      "host": "https://cloud.example.com",
      "username": "your-user",
      "password": "your-app-password"
    }
  }
}

Config location: ~/.config/nextcloud-mcp/config.json (override with NEXTCLOUD_MCP_CONFIG env var).

Docker

docker build -t nextcloud-mcp .
docker run -p 8080:8080 -v ~/.config/nextcloud-mcp:/data nextcloud-mcp

The container stores config at /data/config.json. Mount a host directory to persist it across upgrades.

Configuration

Option	Default	Description
--port	8080	HTTP listen port
NEXTCLOUD_MCP_CONFIG	~/.config/nextcloud-mcp/config.json	Config file path

Instance Config Fields

Field	Required	Description
host	Yes	Nextcloud URL (e.g., https://cloud.example.com)
username	Yes	Nextcloud username
password	Yes	App password (not the account password)
insecure	No	Skip TLS verification for self-signed certs
timezone	No	IANA timezone (e.g. Europe/Berlin) that calendar times are interpreted in. Defaults to $TZ, then UTC

MCP Tools

The server exposes 84 tools across 9 domains. Every tool accepts an optional instance parameter to target a specific Nextcloud instance (defaults to the configured default).

Domain	Tools	Nextcloud API
Config	4	Local config file
Notes	9	Notes REST API
Deck	29	Deck REST API + OCS (comments)
Talk	8	OCS Spreed API v4
Calendar	10	CalDAV
Tasks	5	CalDAV (VTODO)
Files	10	WebDAV + OCS Sharing API
Contacts	6	CardDAV
Search	3	OCS Unified Search

Tool Registration

All tools are registered globally and listed unconditionally — tools/list always returns the full set. There is no per-session state: any client can call any tool at any time, and a server restart never invalidates what a client knows about the toolset.

An earlier design hid each domain's tools behind per-session loader stubs to keep the initial list short. It was removed because MCP clients do not reliably keep a stable session — Claude's clients initialize a fresh session per poll or turn, and each fresh session fell back to the short list, making loaded tools appear to vanish. Clients that need a small tool surface defer tools on their side (e.g. tool search).

Bulk Tools

Acting on twenty items costs twenty tool calls, which is twenty round trips and twenty turns' worth of tokens for what is a for-loop on the server. Four tools take a list instead — nc_deck_bulk_cards, nc_tasks_bulk, nc_notes_bulk, nc_files_bulk — plus the filter-based nc_calendar_bulk_operations for events. They are best effort: an item that fails does not stop the rest, and the result names the ones that failed so only those need a retry. At most 100 items per call.

See docs/features.md for a complete tool reference with parameters, internals, and app requirements.

Endpoints

Method	Path	Description
POST	/mcp	MCP Streamable HTTP endpoint
GET	/health	Health check (returns {"status": "ok"})

Architecture

See docs/dev/architecture.md for the system design and component overview.

Tech Stack

Component	Version
Go	1.26
mcp-go	v0.55.1
Docker base	scratch

License

See LICENSE file.