cloudsuite

cloudsuite lets an agent work with a self-hosted Nextcloud instance: search and edit notes, see calendars and create or delete events, list and create contacts, and browse, read, write, and delete files. Notes go through the instance's Notes app API; calendars, contacts, and files go through Nextcloud's CalDAV, CardDAV, and WebDAV endpoints.

This package is a clean-room rebuild, and a labelled core subset: it covers 15 of the 30 tools documented for the original Nextcloud MCP server. The omitted tools are listed under "Scope" below.

How it talks to the service

Every tool needs three environment variables:

export NEXTCLOUD_URL="https://cloud.example.com"   # base URL of the instance
export NEXTCLOUD_USERNAME="alice"
export NEXTCLOUD_PASSWORD="xxxxx-xxxxx-xxxxx-xxxxx"  # an app password

With any of the three missing, every call fails with an error naming the missing variables, before any request is made. Every request carries HTTP Basic auth built from the username and app password.

Wire-format note: the original project's README documents the tools and their purposes; the endpoint shapes here follow Nextcloud's public Notes API and DAV layout. Notes use {NEXTCLOUD_URL}/index.php/apps/notes/api/v1; calendars use CalDAV under {NEXTCLOUD_URL}/remote.php/dav/calendars/{user}/; contacts use CardDAV under {NEXTCLOUD_URL}/remote.php/dav/addressbooks/users/{user}/; files use WebDAV under {NEXTCLOUD_URL}/remote.php/dav/files/{user}/. Path segments are percent-encoded per segment (slashes preserved). DAV status 207 counts as success; any other non-2xx response is reported with its status and a body excerpt. Calendar event listing is a summary only: the REPORT response is reduced to its status, byte count, and the SUMMARY: lines found in it.

Related MCP server: Nextcloud MCP Server

Install

npx @reneturcios/cloudsuite nextcloud_webdav_list_directory '{"path":"/"}'

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/cloudsuite

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

The CLI mirrors the tools: one subcommand per tool, taking its arguments as a single JSON object.

cloudsuite nextcloud_notes_search_notes '{"query":"shopping"}'
cloudsuite nextcloud_notes_create_note '{"title":"Ideas","content":"..."}'
cloudsuite nextcloud_calendar_list_calendars '{}'
cloudsuite nextcloud_webdav_read_file '{"path":"/Documents/notes.txt"}'
cloudsuite --version

Exit codes: 0 on success, 1 on an API or validation error (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/cloudsuite mcp

MCP client configuration:

{
  "mcpServers": {
    "cloudsuite": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cloudsuite", "mcp"],
      "env": {
        "NEXTCLOUD_URL": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "alice",
        "NEXTCLOUD_PASSWORD": "your app password"
      }
    }
  }
}

Tools

Scope

Omitted from this core subset: hello, nextcloud_calendar_get_event, nextcloud_calendar_update_event, nextcloud_contacts_list_addressbooks, nextcloud_contacts_create_addressbook, nextcloud_contacts_delete_addressbook, nextcloud_contacts_delete_contact, all six nextcloud_tables_* tools, nextcloud_webdav_search_files, and nextcloud_webdav_create_directory. The CalDAV/CardDAV wire shapes are minimal reconstructions: there is no recurrence expansion, ETag handling, or timezone processing, and the calendar event listing extraction is intentionally crude. No live Nextcloud instance was used while building this package; behaviour is covered by fake-fetch tests only.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.