cloudsuite

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.

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

Tool	Input	What it does
nextcloud_notes_search_notes	query (required)	Fetch all notes and keep those whose title or content contains the query (case-insensitive).
nextcloud_notes_create_note	title, content (required), category	Create a note via the Notes API.
nextcloud_notes_update_note	id (required), title, content, category	Update the provided fields of a note.
nextcloud_notes_append_content	id, content (required)	Read the note, then write it back with the new content appended after a newline; the title is preserved.
nextcloud_notes_delete_note	id (required)	Delete a note; returns {status, id}.
nextcloud_calendar_list_calendars	—	PROPFIND the calendars root and return each collection's display name and href.
nextcloud_calendar_create_event	calendarId, summary, dtstart, dtend (required), description, location	PUT a generated VEVENT as an .ics file into the calendar; returns {status, uid}.
nextcloud_calendar_list_events	calendarId (required)	REPORT a calendar-query and summarize the response: status, bytes, and extracted SUMMARY: lines.
nextcloud_calendar_delete_event	calendarId, eventId (required)	DELETE the event resource.
nextcloud_contacts_list_contacts	addressBookId (required)	PROPFIND an address book and return the hrefs it contains.
nextcloud_contacts_create_contact	addressBookId, fullName (required), email, phone, organization	PUT a generated VCARD as a .vcf file into the address book; returns {status, uid}.
nextcloud_webdav_list_directory	path (required)	PROPFIND a folder and return each entry's name, href, and whether it is a collection.
nextcloud_webdav_read_file	path (required)	GET a file and return its text content and byte count.
nextcloud_webdav_write_file	path, content (required)	PUT text content to a file path.
nextcloud_webdav_delete_resource	path (required)	DELETE a file or folder.

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.