module_type: mcp-server
status: active
protocol: mcp
primary_capability: nextcloud-administration
requires: docker, python>=3.10
works_with: nextcloud
last_verified: 2026-08-30

Nextcloud Control Plane MCP Server

Status: Active | Last Verified Date: 2026-08-30

Provides a Model Context Protocol (MCP) server for managing and administering Nextcloud instances via dockerized OCC commands.

What it does / does not do

What it does: Provides an MCP server that securely interfaces with a local Dockerized Nextcloud deployment via OCC (php occ) commands. It allows AI agents to retrieve Nextcloud system status, view/manage trusted domains, perform database optimizations, export Deck Kanban data, and execute arbitrary OCC commands. What it does not do: It does not run Nextcloud itself; it only controls a running Nextcloud Docker container (default: nextcloud_app_1). It interfaces via Docker Exec, not over HTTP via Nextcloud's Provisioning API.

Related MCP server: Nextcloud MCP Server

Why an agent would use it

Agents can use this to administer, configure, troubleshoot, and maintain a Nextcloud instance without requiring SSH access or manual GUI interaction, fully automating tasks like adding trusted domains when network topology changes, optimizing the database after upgrades, or exporting Deck boards.

Architecture and dependencies

• Language: Python 3.10+

• Protocol: Model Context Protocol (FastMCP)

• Integrations: Executes commands against the local Docker daemon via asyncio.create_subprocess_exec.

• Dependencies: mcp>=1.0.0, local Docker CLI.

Compatibility

• Linux, macOS, or any host with a functional Docker CLI.

• Compatible with any MCP client (Claude Desktop, Antigravity).

• Designed for Nextcloud containers running with the www-data user.

Quick start and health check

pip install -e .
nextcloud-mcp-control

Health Check: Once connected via an MCP client, call the get_status tool to verify successful OCC communication with the container.

Configuration and environment variables

No other external environment variables are required beyond the host's standard Docker configuration.

Complete MCP tool/API table with side effects

Security model and trust boundaries

• Trust Boundary: The server assumes the host running it has authorization to execute docker exec against the configured Nextcloud container. The MCP server runs with the same permissions as the user executing it.

• Security Risks: The run_occ tool allows executing arbitrary administrative commands against the Nextcloud instance, which could be destructive (e.g., occ maintenance:install, occ app:disable, etc.). Agents with access to this MCP server have full administrative control over the Nextcloud container.

• Design Philosophy & Upstream Reconciliation: This repository is a specialized, security-hardened reference implementation for TheNovaNodes ecosystem. Unlike some generic or upstream production Docker images (e.g., ghcr.io/cbcoutinho/...) which may blindly expose 90+ tools, this Control Plane intentionally exposes only a strictly minimized subset of critical tools. This deliberate reduction in the attack surface prevents autonomous agents from unintentionally triggering destructive commands, while still preserving manual execution capability via run_occ if explicitly required. (Fixes #3)

Tests and exact commands

Run the test suite using pytest:

pytest

Operations, logs, backup/restore, rollback

• Operations & Logs: Logs are output to standard error via Python's logging module.

• Backup/Restore: Since this server is stateless and interfaces with Nextcloud, standard Nextcloud backup procedures apply (database dump and file backup). No state is stored within the MCP server itself.

• Rollback: To rollback changes made by add_trusted_domain, use run_occ to manually config:system:delete trusted_domains <index>.

Generic MCP-client example

Add this to your mcp_config.json or claude_desktop_config.json:

{
  "mcpServers": {
    "nextcloud-control": {
      "command": "python",
      "args": ["-m", "nextcloud_mcp_control.server"]
    }
  }
}

Limitations and roadmap

• Operates on a single Nextcloud container per server instance (configurable via NC_CONTAINER_NAME).

Related TheNovaNodes modules

• Part of the TheNovaNodes and Antigravity Agent Ecosystem.

License

Refer to the repository license for details.