Nextcloud MCP Server
Provides access to a Nextcloud user's files: list folders, search by name and inside documents, read text/PDF/Office/OpenDocument files, get previews, download files, search file contents, and use Nextcloud's unified search across apps (files, calendar, contacts, Talk, Deck). Also exposes trash bin listing/restoration and, when writes are enabled, tools to create folders, write text files, upload, move, copy and delete files. Signs users in with their own Nextcloud account via Login Flow v2 or OAuth2, acting within their permissions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Nextcloud MCP Server search my Nextcloud for the Q3 budget spreadsheet"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Nextcloud MCP Server
An MCP server that gives Claude (and other MCP clients) access to the files of a Nextcloud user: list, search by name and inside documents, read PDFs and Office files, look at previews, download — and, when you enable it, upload, create, move, copy and delete.
Only the Nextcloud URL is needed. People sign in with their normal Nextcloud login (including 2FA) through Nextcloud's Login Flow v2; no admin setup, no passwords in config files. Nextcloud's OAuth2 app is supported as an alternative.
Each person's own permissions. The server acts as the signed-in user — their files and what is shared with them, nothing else. Access shows up in Nextcloud under Settings → Security → Devices & sessions and can be revoked there.
Read-only by default. Write tools only exist with
NEXTCLOUD_ENABLE_WRITES=true. Nothing is overwritten unless the model passesoverwrite=true; deleted items go to the trash bin and can be restored.Local or hosted. stdio for Claude Code / Claude Desktop on your machine, or Streamable HTTP + OAuth as a remote connector for claude.ai, shared by a whole team.
Setup (local, stdio)
Requires Node.js 22.13 or later.
claude mcp add nextcloud --env NEXTCLOUD_URL=https://cloud.example.com -- npx -y nextcloud-mcpThe first tool call answers with a login link. Open it, log in, click Grant access — the next call works. The app
password Nextcloud creates is saved to ~/.config/nextcloud-mcp/credentials.json (mode 600). To sign in up front:
NEXTCLOUD_URL=https://cloud.example.com npx nextcloud-mcp login # opens the browser
npx nextcloud-mcp --selftest # a few read-only calls
npx nextcloud-mcp logout # revokes the app password in NextcloudAlternatively pass an app password you created yourself as NEXTCLOUD_USER + NEXTCLOUD_APP_PASSWORD.
Enable changes once you trust it: add --env NEXTCLOUD_ENABLE_WRITES=true.
Related MCP server: MCP for Nextcloud
Hosted mode (claude.ai connector)
docker build -t nextcloud-mcp .
docker run -p 3000:3000 -v nextcloud-mcp-data:/data \
-e NEXTCLOUD_URL=https://cloud.example.com \
-e NEXTCLOUD_MCP_PUBLIC_URL=https://nextcloud-mcp.example.com \
-e NEXTCLOUD_MCP_SECRET="$(openssl rand -base64 48)" \
-e NEXTCLOUD_ALLOWED_GROUPS=claude \
nextcloud-mcpIn claude.ai add a custom connector with the URL https://nextcloud-mcp.example.com/mcp. When someone connects it:
claude.ai registers itself (dynamic client registration) and sends the person to this server. Only known redirect URIs may register (see Security).
A consent page names the app and where the access will go (e.g. claude.ai, or an app on your own computer). Nothing is sent to Nextcloud before the person allows it.
Login Flow v2 (default): a page with a Log in to Nextcloud button opens the Nextcloud login in a new tab. After Grant access the page notices on its own and returns to claude.ai. OAuth2 (if
NEXTCLOUD_OAUTH_CLIENT_ID/SECRETare set): the person goes straight to Nextcloud's consent screen.The server checks
NEXTCLOUD_ALLOWED_GROUPS/NEXTCLOUD_ALLOWED_USERS; refused sign-ins are revoked in Nextcloud immediately.
Revoking access in Nextcloud makes the next request fail with 401, and claude.ai asks the person to sign in again. Signing in again from the same client replaces (and revokes) the previous app password, so device lists stay clean. Connections whose tokens all expired are revoked in Nextcloud by a housekeeping job.
Variable | |
| required — the Nextcloud everyone connects to |
| required — public https URL of this server |
| required — ≥ 32 characters; encrypts stored credentials (AES-256-GCM) |
| SQLite file, default |
| comma-separated; empty = every Nextcloud user may connect |
|
|
| comma-separated redirect URIs MCP clients may register, in addition to the built-in ones ( |
|
|
| use Nextcloud OAuth2; register the client under Administration → Security → OAuth 2.0 clients with redirect URI |
|
|
| tokens issued to MCP clients, default 1 h / 90 days |
Login Flow or OAuth2? Both end with a token that carries the user's full Nextcloud permissions — Nextcloud's OAuth2
has no scopes. Login Flow needs no admin setup and creates one revocable app password per connection. OAuth2 shows
Nextcloud's own consent screen and uses short-lived access tokens, but needs a client registered by an admin, and does
not support PKCE. Read-only access is enforced by this server (NEXTCLOUD_ENABLE_WRITES), not by Nextcloud.
Security
The hosted server hands out access to Nextcloud with the full permissions of whoever signs in, so it guards against the "confused deputy" attack described in the MCP security best practices: someone registers their own client with their own redirect URI and sends a colleague the sign-in link — the colleague sees the genuine Nextcloud login, grants access, and the code would end up with the attacker. Two independent checks prevent that:
Redirect allowlist. Dynamic client registration only accepts known redirect URIs;
/authorizechecks again, so narrowing the list also locks out clients registered earlier. Loopback addresses are allowed because a code sent there can only reach the signing-in person's own machine.Consent page. Before forwarding to Nextcloud the person sees the app's (self-declared) name and, more importantly, the address the access goes to. The form is protected by a CSRF token bound to a
SameSite=Strictcookie, so another site cannot submit the consent on the person's behalf.
Other measures: Nextcloud credentials are stored AES-256-GCM encrypted; tokens issued to MCP clients are stored as SHA-256 hashes; refused sign-ins (allowlists) are revoked in Nextcloud immediately; the sign-in pages send a strict CSP and cannot be framed.
Tools
Tool | |
| One folder's content, sortable, paged |
| Size, owner, permissions, flags, link into the web UI |
| Server-side search by name (all words, |
| Text of text files, PDF, docx/xlsx/pptx, odt/ods/odp; images as image; long content in chunks |
| Thumbnail from Nextcloud's preview generator (photos, first PDF page, office, video) |
| Local: streamed to a path. Hosted: returned inline (≤ 10 MB) |
| Finds a phrase inside the newest readable files below a folder, with matching lines |
| Nextcloud's search box across apps (files, calendar, contacts, Talk, Deck, full-text index …) |
| Trash bin with original locations |
| User, groups, quota, Nextcloud version, whether writes are enabled |
| Including missing parents; idempotent |
| Create or (with |
| Any file; local path (stdio) or base64 |
| Rename/move/copy files and folders |
| To the trash bin |
| Back to the original location |
✎ = only with NEXTCLOUD_ENABLE_WRITES=true.
Text extraction is built in and dependency-light: PDFs via unpdf (pdf.js), Office Open
XML and OpenDocument with a small ZIP reader (decompressed size capped against zip bombs). Formatting is dropped;
spreadsheets come out as tab-separated rows per sheet. Scanned PDFs without a text layer have no text — the model can
look at them with nextcloud_get_preview.
Development
npm install
npm test # builds, then runs everything against an in-memory fake Nextcloudtest/helpers/fake-nextcloud.mjs implements the WebDAV, OCS, preview, Login Flow v2 and oauth2 endpoints the server
uses; test/hosted.test.mjs walks the full claude.ai sign-in for both sign-in methods.
License
MIT
Available Tools
10 toolsnextcloud_download_fileDownload fileARead-onlyIdempotent
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.
Inputs: path (required), output_path (required).
nextcloud_get_file_infoFile or folder detailsARead-onlyIdempotent
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.
Inputs: path (required), response_format.
nextcloud_get_previewPreview image of a fileARead-onlyIdempotent
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.
Inputs: path (required), size.
nextcloud_list_filesList folderARead-onlyIdempotent
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.
Inputs: path, sort, type, limit, +2 more.
nextcloud_list_trashList trash binARead-onlyIdempotent
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.
Inputs: limit, query, response_format.
nextcloud_read_fileRead file contentARead-onlyIdempotent
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.
Inputs: path (required), offset, max_chars.
nextcloud_search_file_contentsSearch text inside filesARead-onlyIdempotent
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.
Inputs: query (required), path, documents, max_files, +4 more.
nextcloud_search_filesSearch files by name, type and dateARead-onlyIdempotent
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.
Inputs: path, sort, type, limit, +7 more.
nextcloud_unified_searchNextcloud unified searchARead-onlyIdempotent
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.
Inputs: term (required), limit, providers, response_format.
nextcloud_whoamiCurrent user and serverARead-onlyIdempotent
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.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Browse and manage files in your Moxt AI workspace from any MCP client.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables to manage Nextcloud files, user info, sharing, calendar, and contacts through optimized MCP tools with dynamic tool selection and enterprise-grade security.891MIT
- AlicenseNot gradedqualityAmaintenanceA native Nextcloud app that exposes the instance as an MCP server so Claude and other MCP clients can read, search, and (with admin-granted permissions) edit files, notes, calendars, Deck cards, and Talk conversations. It runs inside Nextcloud with OAuth or app-password sign-in, applying each user's own Nextcloud permissions and admin-controlled per-operation grants.19AGPL 3.0
- AlicenseAqualityCmaintenanceConnects any MCP client to a Nextcloud instance through official WebDAV and OCS APIs, enabling browsing, searching, uploading, downloading, copying, moving, and deleting files and folders, plus managing favorites, public links and user/group shares, and the trash bin. Authentication uses the browser-based Login Flow with a saved app password.23MIT
- AlicenseNot gradedqualityCmaintenanceEnables LLM agents to read and write Nextcloud files, notes, calendars, tasks, contacts, and Talk messages through a secure authenticated MCP endpoint.MIT