nextcloud-mcp
The nextcloud-mcp server provides a FastMCP interface for Nextcloud, exposing administrative occ commands, OCS provisioning, and WebDAV file operations as agent-driven tools.
System Administration (occ tools)
Check Nextcloud status (version, maintenance mode, instance ID)
Get or set maintenance mode
List, enable, or disable apps
Read and write system or app-specific config values
Scan filesystem to update file cache; clean orphaned cache entries
Database maintenance: add missing indices, convert filecache IDs to bigint
Query background job mode or trigger a worker run
Check for available core/app updates and run security advisory checks
Rebuild or reset the full-text search index (OpenSearch)
List configured external storage mounts
Verify push notification connectivity
Tail the Nextcloud log file
Run overall system health checks
User & Group Management (OCS Provisioning)
List, create, enable, or disable user accounts
Create groups and add users to them
Generate app passwords for users
File Operations (WebDAV)
List files/directories, download (base64), upload (base64), move/rename, and delete files or directories
Share Management
Create user, group, or public-link shares with configurable permissions and expiration dates
List existing shares (optionally filtered by path)
Delete shares by ID
Additional: Optional Vault integration for credential brokering and OTLP telemetry support.
Provides tools for Nextcloud administration including occ commands (version check, maintenance mode, app management, config read/write, file scan, database maintenance, background jobs, FTS indexing, security advisory check, log tail, system health), OCS provisioning (user and group management, app password generation), and WebDAV file operations (list, get, put, move, delete files; create/list/delete shares).
Allows fetching credentials from HashiCorp Vault instead of environment variables for configuration, enabling secure credential management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nextcloud-mcp list all Nextcloud users"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nextcloud-mcp
FastMCP server for Nextcloud — exposes occ admin commands, OCS provisioning,
and WebDAV file operations as MCP tools.
Overview
nextcloud-mcp wraps three Nextcloud API surfaces:
occadmin — CLI commands executed viadocker execinside the Nextcloud container. Covers version/health, maintenance mode, app management, config, file scanning, database maintenance, background jobs, FTS indexing, external storage, and log tailing.OCS Provisioning API — HTTP-based user and group management, plus app password generation.
WebDAV + Share API — per-user file list/get/put/move/delete, and share create/list/delete.
Intended for homelab and self-hosted operators who want agent-driven Nextcloud administration.
occ and OCS tools are restricted to privileged agents; WebDAV/share tools are available
per-agent with per-call credentials.
Related MCP server: nextcloud-mcp
Tools
occ Admin (17 tools)
Tool | Description | Key Parameters | Returns |
| Nextcloud version, maintenance state, instance ID | — |
|
| Get or set maintenance mode |
|
|
| List apps or enable/disable one |
|
|
| Read a system or per-app config value |
|
|
| Write a system or per-app config value |
|
|
| Scan filesystem and update file cache |
|
|
| Remove orphaned file cache entries | — |
|
| Add missing database indices | — |
|
| Convert filecache IDs to bigint | — |
|
| Query job mode or trigger a worker run |
|
|
| Check for available core or app updates | — |
|
| Run security advisory check against known CVEs | — |
|
| Rebuild full-text search index (OpenSearch) |
|
|
| List configured external storage mounts | — |
|
| Verify push notification connectivity | — |
|
| Return last N lines of nextcloud.log |
|
|
| Run overall system health check | — |
|
config_setcan break Nextcloud — alwaysconfig_getbefore writing.fulltextsearch_index --resetwipes the OpenSearch index; takes time on large instances.
OCS Provisioning (6 tools)
Tool | Description | Key Parameters | Returns |
| List users, optionally filtered |
|
|
| Create a new user account |
|
|
| Enable or disable a user |
|
|
| Create a user group |
|
|
| Add user to a group |
|
|
| Generate an app password via occ |
|
|
app_password_createreturns the password exactly once — store it in Vault immediately.
WebDAV + Shares (8 tools)
WebDAV tools authenticate as the calling agent's own Nextcloud user (pass username/password
per call). Share tools authenticate as the admin user — required for cross-user share management.
Tool | Description | Key Parameters | Returns |
| List files/directories at a path |
|
|
| Download a file |
|
|
| Upload a file |
|
|
| Move or rename a file/directory |
|
|
| Delete a file or directory |
|
|
| Create a share (user/group/public link) |
|
|
| List shares, optionally by path |
|
|
| Delete a share by ID |
|
|
WebDAV paths are relative to the user's file root — no leading slash needed.
dav_get/dav_put use base64 encoding for binary content.
Environment Variables
Variable | Required | Default | Purpose |
| Yes | — | Nextcloud base URL (e.g. |
| No |
| Docker container name for |
| No |
| Admin username for OCS and share tools |
| Yes* | — | Admin app password (*unless Vault is configured) |
| No | — | Vault address (enables credential brokering) |
| No | — | Vault token (required when |
| No |
| Vault KV v2 path for admin credentials |
| No | — | OTLP trace endpoint (e.g. |
| No |
| Log verbosity |
FastMCP transport (HTTP mode):
Variable | Default | Purpose |
|
| Set to |
|
| Bind port (HTTP mode) |
|
| Bind host (HTTP mode) |
Installation
Prerequisites: Python 3.11+, Docker (for occ tools)
pip install nextcloud-mcpOr from source:
git clone https://github.com/TadMSTR/nextcloud-mcp.git
cd nextcloud-mcp
python3 -m venv .venv
.venv/bin/pip install -e .With optional OTLP telemetry:
pip install 'nextcloud-mcp[telemetry]'Quickstart:
NEXTCLOUD_URL=https://nextcloud.example.com \
NEXTCLOUD_ADMIN_PASSWORD=<app-password> \
nextcloud-mcpDeployment
PM2
Use ecosystem.config.js in the repo root:
# Create env file
mkdir -p /opt/appdata/nextcloud-mcp
cat > /opt/appdata/nextcloud-mcp/env <<'EOF'
NEXTCLOUD_URL=https://nextcloud.example.com
NEXTCLOUD_CONTAINER=nextcloud
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=<app-password>
FASTMCP_TRANSPORT=streamable-http
FASTMCP_PORT=8500
FASTMCP_HOST=127.0.0.1
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
EOF
chmod 600 /opt/appdata/nextcloud-mcp/env
# Load env and start
export $(grep -v '^#' /opt/appdata/nextcloud-mcp/env | xargs)
pm2 start ecosystem.config.js
pm2 saveAdmin app password
Generate a Nextcloud app password for the admin account:
Log in to Nextcloud as admin
Settings → Security → Devices & sessions → Create new app password, label it
mcp-admin
Or via occ after initial setup with a temporary password.
scoped-mcp wiring
Example ~/.claude/manifests/nextcloud-mcp.yaml:
name: nextcloud-mcp
port: 8500
grants:
sysadmin:
tools: "*"
developer:
tools: [dav_list, dav_get, dav_put, dav_move, dav_delete, share_create, share_list, share_delete]
research:
tools: [dav_list, dav_get, share_list]
writer:
tools: [dav_list, dav_get, dav_put, share_create, share_list]
security:
tools: [dav_list, occ_status, security_check, log_tail]Vault integration (optional)
When NEXTCLOUD_VAULT_ADDR and NEXTCLOUD_VAULT_TOKEN are set, admin credentials are
fetched from Vault at call time instead of env vars:
# Store credentials (KV v2 — path includes /data/)
vault kv put secret/nextcloud/admin username=admin password=<app-password>NEXTCLOUD_VAULT_ADDR=http://127.0.0.1:8200
NEXTCLOUD_VAULT_TOKEN=<token>
NEXTCLOUD_VAULT_ADMIN_PATH=secret/data/nextcloud/adminPer-agent file access
Each agent should use its own Nextcloud account and app password, passed per-call to
dav_* and share_* tools. Generate app passwords via:
app_password_create(username="agent-developer", label="forge-developer")Store the returned password in Vault immediately — it is not logged or stored by this server.
Observability
Logs: structlog JSON to stdout. Level controlled by
LOG_LEVEL.Traces: set
OTEL_EXPORTER_OTLP_ENDPOINT(gRPC); requiresnextcloud-mcp[telemetry].occ arg redaction:
--valuearguments are replaced with[REDACTED]in log output.
Forge deployment
See docs/forge.md for the full forge setup walkthrough: venv install, PM2, scoped-mcp manifest details, and Vault credential brokering.
License
MIT
Available Tools
31 toolsapp_manageA
List all apps or enable/disable a specific app by name.
Inputs: action (required), app. Returns: result
app_password_createA
Generate an app password for a user via occ. Returns the password to the caller — never stored or logged by this server. Store it securely (e.g. Vault) immediately after receiving it.
Inputs: username (required), label. Returns: result
background_jobsA
Query background job mode ('mode') or trigger a worker run ('run'). 'run' executes one pass of the background job queue.
Inputs: action. Returns: result
config_getB
Read a system or per-app config value. app_name required when scope='app'.
Inputs: key (required), scope (required), app_name. Returns: result
config_setA
Write a system or per-app config value. Incorrect values can break Nextcloud — prefer config_get before changing.
Inputs: key (required), scope (required), value (required), app_name, +1 more. Returns: result
dav_deleteC
Delete a file or directory from the user's WebDAV space.
Inputs: path (required), password (required), username (required). Returns: result
dav_getA
Download a file. Returns base64-encoded content.
Inputs: path (required), password (required), username (required). Returns: result
dav_listB
List files/directories at a WebDAV path for the given user. Returns raw WebDAV XML (PROPFIND response).
Inputs: password (required), username (required), path. Returns: result
dav_moveC
Move or rename a file or directory within the user's WebDAV space.
Inputs: dst (required), src (required), password (required), username (required). Returns: result
dav_putA
Upload a file. content_b64 must be base64-encoded bytes. Creates the file if it does not exist, overwrites if it does.
Inputs: path (required), password (required), username (required), content_b64 (required). Returns: result
db_add_missing_indicesA
Add missing database indices. Safe to run at any time; recommended after upgrades.
Inputs: no named parameters. Returns: result
db_convert_bigintB
Convert filecache IDs to bigint. Required after large installs or major upgrades.
Inputs: no named parameters. Returns: result
external_storage_listA
List configured external storage mounts as JSON.
Inputs: no named parameters. Returns: result
files_cleanupA
Remove orphaned file cache entries.
Inputs: no named parameters. Returns: result
files_scanB
Scan the filesystem and update the file cache. Provide path (e.g. 'alice/files/Documents') or set all_users=True.
Inputs: path, all_users. Returns: result
fulltextsearch_indexA
Rebuild the full-text search index (OpenSearch). Set reset=True to wipe the index before reindexing.
Inputs: reset. Returns: result
group_add_memberC
Add a user to an existing Nextcloud group.
Inputs: group_id (required), username (required). Returns: result
group_createC
Create a new Nextcloud user group.
Inputs: group_id (required). Returns: object
log_tailA
Return the last N lines of nextcloud.log.
Inputs: lines. Returns: result
maintenance_modeA
Get or set maintenance mode. Omit enable to query current state; pass True/False to change it.
Inputs: enable. Returns: result
notify_push_selftestB
Run the notify_push self-test to verify push notification connectivity.
Inputs: no named parameters. Returns: result
occ_statusA
Return Nextcloud version, maintenance state, and instance ID.
Inputs: no named parameters. Returns: object
security_checkB
Run Nextcloud security advisory check against known CVEs.
Inputs: no named parameters. Returns: result
system_checkB
Run an overall Nextcloud system health check.
Inputs: no named parameters. Returns: result
upgrade_checkB
Check for available Nextcloud core or app updates.
Inputs: no named parameters. Returns: result
user_createC
Create a new Nextcloud user account.
Inputs: password (required), username (required), email, display_name. Returns: object
user_disableB
Enable or disable a Nextcloud user. disable=True to disable, False to re-enable.
Inputs: username (required), disable. Returns: result
user_listB
List Nextcloud users. Optionally filter by search string.
Inputs: limit, offset, search. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Each tool targets a distinct resource and action (e.g., user_create, dav_get, share_list), with no overlapping purposes. Even combined tools like app_manage are clearly described and separate from others.
Most tools follow a resource_action pattern with underscores (user_create, config_get), but a few like background_jobs and occ_status are noun-based, causing minor inconsistency. Overall readable and predictable.
With 31 tools, the count exceeds the 25+ threshold and feels heavy for a single server. While Nextcloud is a complex system, many tools could be consolidated or are too granular.
The set covers major areas (users, groups, shares, DAV, apps, config, maintenance) but lacks delete operations for users/groups and update for shares. External storage is only listable, leaving notable gaps.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes a live Nextcloud instance as an MCP server by dynamically creating tools from OpenAPI definitions of installed apps. Enables natural language interaction with Nextcloud apps like files sharing, provisioning, and calendar management.10-
- AlicenseBqualityDmaintenanceMCP server integrating Nextcloud services (tasks, calendar, notes, email, files, Deck) for AI assistant interaction.201MIT
- AlicenseAqualityBmaintenanceAn MCP server that exposes Nextcloud APIs as tools for AI assistants, enabling management of files, calendar, contacts, conversations, and more.2221MIT
- FlicenseNot gradedqualityBmaintenanceA MCP server for accessing Nextcloud Collectives, allowing MCP clients to list, read, and edit collectives, their pages, and tags.-