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

Nextcloud Control Plane MCP Server

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

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, and execute arbitrary OCC commands. What it does not do: It does not run Nextcloud itself; it only controls an existing nextcloud-app Docker container. 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, or optimizing the database after upgrades.

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, httpx>=0.27.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 the nextcloud-app container running Nextcloud 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

• CONTAINER_NAME (internal constant in src/nextcloud_mcp_control/server.py): Target Docker container (hardcoded to nextcloud-app). No specific external environment variables are currently required other than 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 nextcloud-app 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.

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

• Hardcoded container name (nextcloud-app) prevents managing multiple Nextcloud instances on the same host without code changes.

Related TheNovaNodes modules

• Part of the TheNovaNodes and Antigravity Agent Ecosystem.

License

Refer to the repository license for details.