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