module_type: mcp_server
status: active
protocol: mcp
primary_capability: nextcloud_webdav_ocs
requires: nextcloud, httpx
works_with: claude_desktop, ai_agents
last_verified: 2026-08-21

nextcloud-mcp-gateway

Nextcloud Data Plane MCP Server for AI Agents to read, write, and manage files via WebDAV and OCS API.

Status and Last Verified Date

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

Related MCP server: nextcloud-mcp

What it does / does not do

What it does:
Exposes Nextcloud file operations (WebDAV) and user information (OCS API) to AI agents via the Model Context Protocol (MCP). It allows listing, reading, creating, and deleting files and folders, checking instance health and user quotas, and interacting with Nextcloud Deck (Kanban boards and cards) and Calendars (CalDAV).

What it does not do:
It does not administer the Nextcloud instance (e.g., creating users, configuring plugins, changing server settings), nor does it provide a full web GUI. It handles only data-plane operations scoped to the authenticated user.

Why an agent would use it

An AI agent can use this gateway to interact with a user's Nextcloud storage. Agents can read documents or code stored in Nextcloud, generate reports, write logs, organize files into folders, and delete temporary resources. With Deck and Calendar integration, agents can act as personal assistants, organizing tasks and scheduling events, seamlessly integrating AI workflows with the user's personal cloud.

Architecture and Dependencies

• Language: Python 3.10+

• Frameworks/Libraries: mcp (FastMCP framework), httpx (async HTTP client), pydantic.

• APIs Used: Nextcloud WebDAV (/remote.php/webdav) and Nextcloud OCS REST API (/ocs/v1.php/cloud).

• Execution: Runs as a standard stdio MCP server.

Compatibility

Compatible with Python 3.10+ and any standard MCP client (e.g., Claude Desktop). Requires a running Nextcloud instance reachable via HTTP/HTTPS.

Quick Start and Health Check

# Clone the repository
git clone https://github.com/TheNovaNodes/nextcloud-mcp-gateway.git
cd nextcloud-mcp-gateway

# Install dependencies and the CLI tool
pip install -e .

# The server can be started using the Python module execution:
python -m nextcloud_mcp_gateway.server

Health Check: Agents can call the nextcloud_health tool which checks the /status.php endpoint of the configured Nextcloud instance.

Configuration and Environment Variables

Copy .env.example to .env and fill in credentials.

Complete MCP Tool/API Table with Side Effects

Security Model and Trust Boundaries

• Authentication: Relies on HTTP Basic Authentication using NC_USER and NC_APP_PASSWORD. It is highly recommended to use Nextcloud App Passwords rather than main account passwords.

• Authorization: Operations are limited entirely by the permissions of the authenticated user in Nextcloud.

• Network Boundaries: The server must be able to reach NC_URL over the network. Credentials are sent in HTTP headers (use HTTPS for NC_URL in production).

Tests and Exact Commands

Unit tests are written using pytest and pytest-asyncio. Run them with:

python3 -m pytest -v

Operations, Logs, Backup/Restore, Rollback

• Operations: The gateway itself is a stateless service.

• Logs: Handled via the MCP client's standard error stream.

• Backup/Restore: Since the server is stateless, no local backup is necessary. Actual file data should be backed up within the Nextcloud ecosystem.

• Rollback: Roll back to a previous git commit or package version if an update fails.

Generic MCP-Client Example

{
  "mcpServers": {
    "nextcloud-gateway": {
      "command": "nextcloud-mcp-gateway",
      "env": {
        "NC_URL": "https://your-nextcloud.com",
        "NC_USER": "agent_user",
        "NC_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Limitations and Roadmap

• Limitations:

  • read_file only supports textual data and decodes via standard text formats. Binary files may fail or corrupt if requested this way.

  • list_files is limited to a depth of 1 (current directory only).

• Roadmap:

  • Add support for binary file transfers.

  • Support recursive folder listings.

  • Enhanced error handling for large file transfers.

Related TheNovaNodes Modules

Part of the TheNovaNodes AI infrastructure integrations, providing seamless data plane access.

License

MIT License