Skip to main content
Glama
Nextcloud MCP Server

Nextcloud MCP Server

by stack74

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
NEXTCLOUD_URLNoThe Nextcloud URL everyone connects to. Required.
NEXTCLOUD_USERNoNextcloud username for app-password authentication; used with NEXTCLOUD_APP_PASSWORD.
NEXTCLOUD_MCP_SECRETNoAt least 32 characters; encrypts stored credentials with AES-256-GCM. Required in hosted mode.
NEXTCLOUD_MCP_DB_PATHNoSQLite file path./data/nextcloud-mcp.sqlite
NEXTCLOUD_APP_PASSWORDNoNextcloud app password for app-password authentication; used with NEXTCLOUD_USER.
NEXTCLOUD_ALLOWED_USERSNoComma-separated allowed Nextcloud users; empty means every Nextcloud user may connect.
NEXTCLOUD_ENABLE_WRITESNoSet to true to register write tools; read-only by default.false
NEXTCLOUD_MCP_ICON_PATHNoPath to .svg/.png/.ico served as favicon and announced as server icon.
NEXTCLOUD_ALLOWED_GROUPSNoComma-separated allowed Nextcloud groups; empty means every Nextcloud user may connect.
NEXTCLOUD_MCP_PUBLIC_URLNoPublic HTTPS URL of this server. Required in hosted mode.
NEXTCLOUD_OAUTH_CLIENT_IDNoNextcloud OAuth2 client ID; use Nextcloud OAuth2 instead of Login Flow v2.
NEXTCLOUD_OAUTH_CLIENT_SECRETNoNextcloud OAuth2 client secret; use Nextcloud OAuth2 instead of Login Flow v2.
NEXTCLOUD_MCP_ACCESS_TOKEN_TTLNoAccess token TTL issued to MCP clients; default 1 hour.
NEXTCLOUD_MCP_REFRESH_TOKEN_TTLNoRefresh token TTL issued to MCP clients; default 90 days.
NEXTCLOUD_MCP_ALLOWED_REDIRECT_URISNoComma-separated additional redirect URIs MCP clients may register, in addition to built-in ones.
NEXTCLOUD_MCP_DEFAULT_REDIRECT_URISNoSet 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_files searches the whole Nextcloud by name, type and date in one request.

  • "What did I/we work on recently?" -> nextcloud_search_files without a query (newest first).

  • Words INSIDE documents -> nextcloud_search_file_contents with the narrowest folder you can name. It reads files one by one, so a broad folder only covers the newest files.

  • nextcloud_list_files is for looking into one known folder.

  • nextcloud_unified_search covers other Nextcloud apps (calendar, contacts, Talk, Deck, …) and, if installed, the full-text index.

Reading

  • nextcloud_read_file returns 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_whoami confirms 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 with nextcloud_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

CapabilityDetails
tools
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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.

  • By name: 'query' matches parts of the file name; several words must all appear ('rechnung 2026'). '' is a wildcard ('.pdf', 'Angebot*').

  • By type: 'type' = image, pdf, document (Word/ODT), spreadsheet (Excel/ODS/CSV), presentation, text, audio, video or folder.

  • By date: 'modified_after' / 'modified_before' (YYYY-MM-DD).

  • Without 'query' this lists the most recently changed files — the answer to 'what was I working on'.

This searches names, not content. For words inside files use nextcloud_search_file_contents.

nextcloud_read_fileA

Read what is in a file.

  • Text files (txt, md, csv, json, xml, code, …): the text.

  • PDF, Word (docx/odt), Excel (xlsx/ods) and PowerPoint (pptx/odp): the extracted text (PDF per page, spreadsheets per sheet as tab-separated rows; formatting and images are dropped, spreadsheet dates appear as numbers). Scanned PDFs without a text layer return little or nothing — use nextcloud_get_preview to look at them.

  • Images: the image itself (scaled down).

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.9/5.0

Scored across 10 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness2/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues