Skip to content

Usage — API / CLI / MCP

nextcloud-agent exposes the same capability three ways: as MCP tools an agent calls, as a Python API (NextcloudAPI) the operator import, and as a graph-agent CLI. The complete tool surface and ecosystem role are in Overview.

As an MCP server

Once deployed, the server registers one typed tool per operation, nextcloud_<operation>, in ten domains. Each domain is gated by a toggle (all default True): FILESTOOL, SHARESTOOL, CALENDARTOOL, CONTACTSTOOL, TALKTOOL, DECKTOOL, NOTESTOOL, OFFICETOOL, ACTIVITYTOOL, ADMINTOOL. The full list is in the README. Example requests:

  • "List the files in my Documents folder" → nextcloud_list_files(path="Documents")
  • "Share Team/launch/poster.png with a link that expires in two weeks" → nextcloud_create_share(path=..., share_type="public_link", expire_date=...)
  • "Book a review on Friday at 3pm with Ana" → nextcloud_create_event(..., attendees=[...]) (the invitation stays a draft unless send_invitations=true)
  • "Post the update in the launch channel" → nextcloud_send_message(token, message)

As a Python API

NextcloudAPI is a requests-based facade over the Nextcloud WebDAV, CalDAV, CardDAV, and OCS surfaces, composed from per-domain sub-clients.

from nextcloud_agent.api_client import NextcloudAPI

api = NextcloudAPI(
    base_url="https://nextcloud.example.com",
    username="your-user",
    password="your-app-password",
)

# Reads
files = api.list_files("/Documents")  # WebDAV listing
calendars = api.list_calendars()  # CalDAV calendars
events = api.list_events(calendars[0]["url"])  # CalDAV events
contacts = api.list_contacts(api.list_address_books()[0]["url"])  # CardDAV contacts
shares = api.list_shares()  # OCS shares

Build a client straight from the environment with the get_client context manager, which reads NEXTCLOUD_URL, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD. TLS trust is resolved through the shared Agent Utilities TLS profile contract; select NEXTCLOUD_TLS_PROFILE or supply a runtime CA-bundle secret reference without changing application code:

from nextcloud_agent.auth import get_client

with get_client() as api:  # reads NEXTCLOUD_* from the environment / .env
    info = api.get_user_info()

get_client raises a clear authentication error when the supplied credentials are not valid for the target instance, and remains inactive when credentials are absent.

Writes

api.create_folder("/Reports/2026")
api.write_file("/Reports/2026/summary.txt", "...")
api.create_share("/Reports/2026/summary.txt", share_type="public_link", expire_date="2026-12-31")
api.create_event(calendars[0]["url"], summary="Standup", start="2026-06-10T09:00:00Z")

As an agent CLI

The integrated Pydantic-AI graph agent (nextcloud-agent) calls the MCP server and exposes an optional web UI. Point it at a running MCP server and a model provider:

export MCP_URL=http://localhost:8000/mcp
export NEXTCLOUD_URL=https://nextcloud.example.com
export NEXTCLOUD_USERNAME=your-user
export NEXTCLOUD_PASSWORD=your-app-password

nextcloud-agent --provider openai --model-id gpt-4o

A lightweight router node classifies each query into a domain (files, calendar, contacts, sharing, user) and dispatches it to a focused executor, keeping the LLM context compact. See Deployment for running the agent as a long-lived service.