```yaml
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.

## 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
```bash
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

| Variable | Description | Default |
| :--- | :--- | :--- |
| `NC_CONTAINER_NAME` | Target Nextcloud Docker container name | `nextcloud_app_1` |

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

## Complete MCP tool/API table with side effects

| Tool/API | Description | Side Effects |
| --- | --- | --- |
| `get_status()` | Gets Nextcloud system status via `occ status --output=json`. | **None**: Read-only operation. |
| `get_trusted_domains()` | Lists configured trusted domains in Nextcloud. | **None**: Read-only operation. |
| `add_trusted_domain(domain: str)` | Adds a new trusted domain to Nextcloud configuration. | **Modifies State**: Updates `config/config.php` inside the Nextcloud container. |
| `optimize_db()` | Runs missing indices, missing columns, missing primary keys, and filecache bigint conversions. | **Modifies State**: Alters database schema and indices. |
| `export_deck(user_id: str = "admin")` | Exports Nextcloud Deck boards and cards for a specific user via `occ deck:export`. | **None**: Read-only operation. |
| `run_occ(command: str)` | Executes arbitrary OCC command inside the Nextcloud container. | **Variable**: Depending on the specific OCC command invoked. |

## 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:
```bash
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`:
```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.