Nextcloud MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NEXTCLOUD_URL | No | The Nextcloud URL everyone connects to. Required. | |
| NEXTCLOUD_USER | No | Nextcloud username for app-password authentication; used with NEXTCLOUD_APP_PASSWORD. | |
| NEXTCLOUD_MCP_SECRET | No | At least 32 characters; encrypts stored credentials with AES-256-GCM. Required in hosted mode. | |
| NEXTCLOUD_MCP_DB_PATH | No | SQLite file path. | /data/nextcloud-mcp.sqlite |
| NEXTCLOUD_APP_PASSWORD | No | Nextcloud app password for app-password authentication; used with NEXTCLOUD_USER. | |
| NEXTCLOUD_ALLOWED_USERS | No | Comma-separated allowed Nextcloud users; empty means every Nextcloud user may connect. | |
| NEXTCLOUD_ENABLE_WRITES | No | Set to true to register write tools; read-only by default. | false |
| NEXTCLOUD_MCP_ICON_PATH | No | Path to .svg/.png/.ico served as favicon and announced as server icon. | |
| NEXTCLOUD_ALLOWED_GROUPS | No | Comma-separated allowed Nextcloud groups; empty means every Nextcloud user may connect. | |
| NEXTCLOUD_MCP_PUBLIC_URL | No | Public HTTPS URL of this server. Required in hosted mode. | |
| NEXTCLOUD_OAUTH_CLIENT_ID | No | Nextcloud OAuth2 client ID; use Nextcloud OAuth2 instead of Login Flow v2. | |
| NEXTCLOUD_OAUTH_CLIENT_SECRET | No | Nextcloud OAuth2 client secret; use Nextcloud OAuth2 instead of Login Flow v2. | |
| NEXTCLOUD_MCP_ACCESS_TOKEN_TTL | No | Access token TTL issued to MCP clients; default 1 hour. | |
| NEXTCLOUD_MCP_REFRESH_TOKEN_TTL | No | Refresh token TTL issued to MCP clients; default 90 days. | |
| NEXTCLOUD_MCP_ALLOWED_REDIRECT_URIS | No | Comma-separated additional redirect URIs MCP clients may register, in addition to built-in ones. | |
| NEXTCLOUD_MCP_DEFAULT_REDIRECT_URIS | No | Set to false to drop built-in redirect URIs, allowing only configured ones. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server gives access to the files of ONE Nextcloud user — the person who connected it — with exactly their permissions: their own files plus everything shared with them.
Finding things
Do not walk the folder tree to find something.
nextcloud_search_filessearches the whole Nextcloud by name, type and date in one request."What did I/we work on recently?" ->
nextcloud_search_fileswithout a query (newest first).Words INSIDE documents ->
nextcloud_search_file_contentswith the narrowest folder you can name. It reads files one by one, so a broad folder only covers the newest files.nextcloud_list_filesis for looking into one known folder.nextcloud_unified_searchcovers other Nextcloud apps (calendar, contacts, Talk, Deck, …) and, if installed, the full-text index.
Reading
nextcloud_read_filereturns text for text files, PDFs, Word, Excel, PowerPoint and OpenDocument files, and the image itself for pictures. Long content comes in chunks: follow the offset it gives you instead of guessing.Scanned PDFs have no text layer -> look at them with
nextcloud_get_preview.Paths are case-sensitive and start at the user's root, e.g. "/Documents/Offer 2026.pdf". Copy them exactly from list/search results.
Changing files (only if the write tools are present)
If upload/create/move/delete tools are missing, the server is read-only. Say so;
nextcloud_whoamiconfirms it.Nothing is overwritten unless you pass overwrite=true. Only do that when the user asked to replace the file.
Before
nextcloud_delete, tell the user exactly what will be deleted and get a clear yes. Deleted items go to the trash bin and can be restored withnextcloud_restore_from_trash.Moving or deleting files in folders shared with others affects those people too.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| nextcloud_list_filesA | List the files and subfolders of one folder (not recursive). Returns name, type, size, last modified and flags (favorite, shared). Start at '/' to see the top level. To find something whose location you do not know, use nextcloud_search_files instead of walking folders. |
| nextcloud_get_file_infoA | Details of one file or folder: size, type, last modified, owner, permissions, favorite/shared flags, file ID and a link that opens it in the Nextcloud web interface. |
| nextcloud_search_filesA | Find files and folders anywhere below a folder, searched on the Nextcloud server — fast, one request.
This searches names, not content. For words inside files use nextcloud_search_file_contents. |
| nextcloud_read_fileA | Read what is in a file.
Long content comes in chunks of 'max_chars'; the result says which 'offset' to request next. Files above 10 MB are not read. |
| nextcloud_get_previewA | A thumbnail image of a file as Nextcloud renders it: photos, PDFs (first page), office documents and videos, depending on the preview providers the server has enabled. Use it to look at scanned documents, layouts or pictures without downloading the full file. |
| nextcloud_download_fileA | Download a file from Nextcloud. The file is streamed to 'output_path' on this computer; its content is NOT loaded into the conversation, so this works for large files. Returns the saved path and size. To just read a document's text, nextcloud_read_file is the better choice. |
| nextcloud_search_file_contentsA | Search for a word or phrase INSIDE files below a folder and return the matching lines. Reads the most recently changed readable files (text, CSV, Markdown, PDF, Word, Excel, PowerPoint, OpenDocument) one by one, so it is bounded by 'max_files' — narrow 'path' to the right folder for best results. Scanned PDFs without a text layer cannot be searched. To find files by NAME use nextcloud_search_files (much faster). If the server has a full-text index, nextcloud_unified_search may also find content across all files. |
| nextcloud_unified_searchA | Nextcloud's own search box: one term across the installed apps — file names, and depending on the server also calendar events, contacts, Talk messages, Deck cards, notes, mail, and file CONTENTS when the full-text search app is installed (provider 'fulltextsearch'). Without 'providers' all apps are searched and the result lists the provider IDs; pass 'providers' (e.g. ['files']) to narrow a follow-up search. |
| nextcloud_whoamiA | Who is connected: Nextcloud user, display name, e-mail, groups, storage quota, plus the Nextcloud server and whether this MCP server allows changes (upload, create, move, delete). Call this when unsure whether a write tool should exist. |
| nextcloud_list_trashA | List deleted files and folders in the user's trash bin, newest first, with their original location. Restore one with nextcloud_restore_from_trash (needs write access) or in the Nextcloud web interface. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Most tools target distinct actions/resources, and the descriptions explicitly guide users between the three search tools and the three file-access tools. There is still some overlap between nextcloud_search_files, nextcloud_search_file_contents, and nextcloud_unified_search, plus nextcloud_read_file vs nextcloud_get_preview vs nextcloud_download_file, but the boundaries are mostly clear.
All tools use a consistent nextcloud_ prefix and snake_case, with mostly verb_noun naming such as list_files, get_file_info, search_files, read_file, and download_file. Minor deviations like whoami and unified_search keep it from being a perfect verb_noun pattern throughout.
Ten tools is well-scoped for a Nextcloud file/search server. Each tool covers a distinct capability such as identity, listing, metadata, search, read, preview, download, trash listing, and unified search.
The surface is heavily read-only and lacks write/lifecycle operations such as upload, create folder, move/rename, delete, and restore. More importantly, nextcloud_list_trash explicitly references nextcloud_restore_from_trash, but that tool is absent, creating a dead end for agents.