Provides tools for interacting with a Nextcloud account, enabling file and folder management over WebDAV (list, stat, read, write, create, move, delete), filename search via WebDAV SEARCH, and creation of public share links via the OCS Share API.
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 search for budget.xlsx and create a public share link for it"
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.
MCP server for one Nextcloud account. Agents list, read, write, create, move, and delete files over WebDAV, create public share links over the OCS Share API, and search file names with WebDAV SEARCH. Credentials stay in environment variables. This repository does not ship secrets.
Nextcloud auth is HTTP Basic with the user id and an app password (an app token). The server does not use browser login, session cookies, or Login Flow v2/OAuth.
Work | Protocol | Endpoint |
List, stat, read, write, mkdir, move, delete | WebDAV |
|
Filename search | WebDAV |
|
Public share link | OCS Share API |
|
OCS is used only for share links, which WebDAV does not create. File bytes and folders never go through the browser or the OCS files API. delete requires confirm: true (and recursive: true for a folder). Paths that contain .. are rejected before any request.
CI runs mocked WebDAV and OCS responses. It does not call a live Nextcloud, so a LAN-only instance is fine.
The server speaks stdio for Cursor and Grok Bot, and optional Streamable HTTP (JSON, with SSE when a response streams) for a remote client.
Related MCP server: Nextcloud MCP Server
Tool | What it does |
| Immediate children of a folder. Not recursive. |
| Metadata for one file or folder (file info). |
| UTF-8 text, or base64 when you ask. Refuses binary text and files over the read limit. |
| Upload a file. Refuses to replace an existing file unless |
| Create a folder. |
| Move or rename. |
| Delete one path. Requires |
| Public link (OCS |
| Filename substring via WebDAV SEARCH. Not full-text content search. |
Paths are relative to the signed-in user's files. "" and "/" are the files root. .., encoded .., backslashes, and URLs are rejected.
delete never removes the files root. There is no multi-path delete and no account wipe. Nextcloud's own DELETE on a folder removes that folder's contents, so a folder delete stays gated behind recursive: true.
write_file and mkdir accept parents: true to create missing parent folders. They do not delete anything to do it.
Node.js 20 or newer
A Nextcloud account and an app password
git clone https://github.com/wckdboy/nextcloud-mcp.git
cd nextcloud-mcp
npm ci
npm run build
cp .env.example .env
# edit .env — see below
npm run mcpnpm run mcp and npm start are the stdio server (node dist/index.js). A .env file in the working directory is loaded for local runs and does not override variables that are already set. MCP hosts should pass the variables themselves.
Check the project without a Nextcloud server:
npm run typecheck
npm test
npm run buildnpm test uses mocked WebDAV and OCS responses.
Required:
Name | Example | Purpose |
|
| Base URL. A trailing slash is removed. No user, password, query, or fragment. |
|
| Nextcloud user id. |
| (app token) | App password from Settings → Security → Devices & sessions. Not the account password. |
Optional:
Name | Default | Purpose |
|
| Read ceiling. Hard max |
|
| Upload ceiling. Hard max |
|
| Per-request timeout. |
|
| Bind address for |
|
| Bind port for |
| unset | If set, HTTP requests must send |
| unset | Comma-separated |
Copy .env.example. Do not commit .env.
If any of the three required variables is missing, the process exits before it listens. The error names the missing variables and does not ask for a password.
Every WebDAV call (/remote.php/dav/files/<user>/…) and every OCS call sends:
Authorization: Basic base64(NEXTCLOUD_USERNAME:NEXTCLOUD_APP_PASSWORD)NEXTCLOUD_APP_PASSWORD is the app token Nextcloud shows once when you create an app password. The server never reads a session cookie, never starts Login Flow v2, and never performs an OAuth login. Redirects are not followed, so a login page cannot become a session.
Do not paste the Nextcloud account password or the app token into chat. Put the app token in the MCP server environment as NEXTCLOUD_APP_PASSWORD. Agents should ask only for that secret name if it is unset.
Sign in to Nextcloud in a browser.
Open the avatar menu and choose Personal settings (or Settings).
Open Security.
Find Devices & sessions (also labeled App passwords on some versions).
Type an app name such as MCP.
Choose Create new app password.
Copy that app token into NEXTCLOUD_APP_PASSWORD. Nextcloud shows it once. This is not your account password.
Set NEXTCLOUD_USERNAME to the account user id (the id used to sign in, not necessarily the display name).
Set NEXTCLOUD_URL to the site origin, for example https://cloud.example.com. If Nextcloud lives in a subdirectory, include it: https://cloud.example.com/nextcloud.
WebDAV is then NEXTCLOUD_URL/remote.php/dav/files/NEXTCLOUD_USERNAME/. Share links use NEXTCLOUD_URL/ocs/v2.php/apps/files_sharing/api/v1/shares. Both use the same Basic header.
Put this in the user file ~/.cursor/mcp.json, or in the project file .cursor/mcp.json if that file is gitignored. Use an absolute path. Keep the password out of the repository.
{
"mcpServers": {
"nextcloud": {
"command": "node",
"args": ["/ABSOLUTE/PATH/nextcloud-mcp/dist/index.js"],
"env": {
"NEXTCLOUD_URL": "https://cloud.example.com",
"NEXTCLOUD_USERNAME": "your-user-id",
"NEXTCLOUD_APP_PASSWORD": "your-app-password"
}
}
}
}Secret names: NEXTCLOUD_URL, NEXTCLOUD_USERNAME, NEXTCLOUD_APP_PASSWORD.
Reload MCP servers in Cursor after saving. The stdio process is how Cursor launches the server. A URL on your laptop is not required.
From a machine that can npm install this public repo, the same server can be started without a local clone:
{
"mcpServers": {
"nextcloud": {
"command": "npx",
"args": ["-y", "--package", "github:wckdboy/nextcloud-mcp", "nextcloud-mcp"],
"env": {
"NEXTCLOUD_URL": "https://cloud.example.com",
"NEXTCLOUD_USERNAME": "your-user-id",
"NEXTCLOUD_APP_PASSWORD": "your-app-password"
}
}
}
}npm runs prepare, which compiles TypeScript, then runs the nextcloud-mcp binary.
Grok Bot runs the MCP process on its cloud computer. It cannot reach localhost on your laptop. Add a custom stdio server and store the three secrets on that server entry.
In the bot chat:
Add a custom MCP server called nextcloud that runs:
npx -y --package github:wckdboy/nextcloud-mcp nextcloud-mcp
Set these environment variables on the server entry. Store the values as secrets:
NEXTCLOUD_URL
NEXTCLOUD_USERNAME
NEXTCLOUD_APP_PASSWORDCommand: npx
Args: -y, --package, github:wckdboy/nextcloud-mcp, nextcloud-mcp
Secret names: NEXTCLOUD_URL, NEXTCLOUD_USERNAME, NEXTCLOUD_APP_PASSWORD
Confirm when the bot repeats the command and the variable names. Store the app token as NEXTCLOUD_APP_PASSWORD on that server entry. Do not paste the Nextcloud account password or the app token into the chat. Attach the server with @ if the bot does not pick it up on its own. A server saved only in Cursor's mcp.json is not automatically available in Grok Bot; add it there with the message above.
If the bot's computer already has a built checkout, use command node and args /ABSOLUTE/PATH/nextcloud-mcp/dist/index.js with the same three variables.
This is the grok CLI, not the Grok Bot chat UI. Either form uses the same secret names.
grok mcp add nextcloud -- \
npx -y --package github:wckdboy/nextcloud-mcp nextcloud-mcpThen set the variables in ~/.grok/config.toml so the values can come from your environment:
[mcp_servers.nextcloud]
command = "npx"
args = ["-y", "--package", "github:wckdboy/nextcloud-mcp", "nextcloud-mcp"]
enabled = true
[mcp_servers.nextcloud.env]
NEXTCLOUD_URL = "${NEXTCLOUD_URL}"
NEXTCLOUD_USERNAME = "${NEXTCLOUD_USERNAME}"
NEXTCLOUD_APP_PASSWORD = "${NEXTCLOUD_APP_PASSWORD}"grok mcp doctor nextcloud checks the process. Grok expands ${VAR} when it loads the file.
Custom connectors at grok.com/connectors need a public HTTPS MCP URL. The stdio command above is the one Grok Bot should run. The HTTP mode below is loopback unless you put it behind your own TLS proxy and set MCP_HTTP_TOKEN.
npm run mcp:httpThat is node dist/index.js --http. The MCP endpoint is http://127.0.0.1:8787/mcp. GET /health returns {"ok":true,"name":"nextcloud-mcp"} and no credentials.
The transport is Streamable HTTP: a normal JSON response, or an SSE stream when the session needs one. On loopback, Host and Origin are limited to localhost. Set MCP_HTTP_TOKEN to require Authorization: Bearer <token>.
Binding a non-loopback address also requires MCP_HTTP_TOKEN and MCP_HTTP_ALLOWED_HOSTS (the hostnames clients send in Host).
search sends a WebDAV SEARCH request (RFC 5323) to /remote.php/dav/, scoped to files/<user>/<folder> with depth infinity. The match is a substring of displayname (the file name). It does not search inside file contents. %, _, and \ in the query are removed so they are not LIKE wildcards. Results default to 25 and cannot exceed 100. If the server returns HTTP 405 or 501, that instance does not allow WebDAV SEARCH.
npm run typecheck # tsc --noEmit
npm test # mocked WebDAV and OCS
npm run build # dist/
npm run check # typecheck and testCI runs typecheck, test, and build on Node 22. No live Nextcloud.
MIT
Delete one file or one folder. Requires confirm: true. Deleting a folder also requires recursive: true because Nextcloud removes the folder's contents. Refuses the files root. There is no recursive account wipe and no multi-path delete.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File or folder path relative to the Nextcloud files root. | |
| confirm | Yes | Must be true. The tool refuses to delete otherwise. | |
| recursive | No | Must be true to delete a folder. Nextcloud DELETE on a folder removes everything inside it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (destructive, non-idempotent, openWorld), and the description adds real behavioral context beyond them: the mandatory confirm gate, the folder-recursive requirement with its reason, and explicit refusal of the files root. It also rules out account-wipe and multi-path behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each earning its place: action, required flag, conditional flag with rationale, and hard refusals. Front-loaded with the core action and zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-target delete with no output schema, it covers the required flags, the recursive precondition, and the refused edge cases. Nothing an agent needs to invoke it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning by tying recursive specifically to folder deletion and explaining why Nextcloud requires it (contents removed). It reinforces the confirm gate rather than merely restating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Delete one file or one folder') and pins down scope ('one', not multi-path). An agent can immediately separate this from siblings like move or write_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear usage conditions (confirm: true, recursive: true for folders) and negative scope (no account wipe, no multi-path delete, refuses files root). It stops short of explicitly naming an alternative sibling for relocation or batch deletion, so it is clear but not fully routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the immediate children of a folder in the signed-in user's Nextcloud files. Not recursive. path is relative to the files root.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Folder path relative to the Nextcloud files root. Omit or pass an empty string for the root. | |
| limit | No | Maximum entries to return. Default 200. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the meaningful scoping constraint (non-recursive, immediate children only) but says nothing about pagination, ordering, or the default limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste, with the core scope constraint (immediate children, not recursive) front-loaded before the path clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with fully documented parameters and annotations covering the safety profile, the description is nearly sufficient. It omits return-shape hints (entries, ordering, truncation at the limit), which a listing tool could usefully mention given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with only 2 simple parameters, so the baseline is 3. The description's 'path is relative to the files root' restates what the schema already says, and it does not address the limit parameter at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (immediate children of a folder) plus a scope boundary (not recursive). It is clear what it does, though it does not name a sibling (e.g. search) to sharpen the distinction against alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Not recursive' note implies the usage context versus a recursive/search tool, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative among the siblings (search, stat).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a folder with WebDAV MKCOL. Set parents true to create missing ancestors. Refuses when a path segment already exists as a file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Folder path relative to the Nextcloud files root. | |
| parents | No | Create missing ancestor folders. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write/non-idempotent/non-destructive profile, so the bar is lower. The description adds real behavioral context beyond them: the MKCOL mechanism, the ancestor-creation semantics of parents, and the explicit refusal condition when a path segment exists as a file. It stops short of describing errors for other cases (permissions, existing folder) or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler, front-loaded with the operation and protocol, followed by the flag behavior and the failure mode. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, no-output-schema tool with full annotation coverage, the description supplies the operation, flag semantics, and the main failure mode, which is enough to call it correctly. Only sibling routing and non-refusal error behavior are left unstated, a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented, and the baseline is 3. The description restates the parents semantics already present in the schema and adds only the default-false emphasis, offering marginal extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Create a folder") and even names the underlying protocol operation (WebDAV MKCOL), which is unambiguous. It does not differentiate from siblings like write_file, which could also implicitly create a directory path, so an agent gets clarity about the operation but not about sibling routing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the parents flag and when the call will fail (path segment already a file), which is implied usage guidance. It never states when to prefer mkdir over write_file or list_directory, and offers no prerequisites or confirmation of ordering relative to other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move or rename a file or folder with WebDAV MOVE. overwrite defaults to false. Refuses to move the files root or a folder into itself.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | New path, relative to the files root. This is a move, not a copy. | |
| from | Yes | Existing file or folder path, relative to the files root. | |
| overwrite | No | Replace the destination if it exists. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds real behavioral detail beyond that: overwrite defaults to false, and the server refuses to move the files root or a folder into itself, which tells the agent about failure modes it would otherwise have to discover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero waste; the core operation is front-loaded and the constraints follow compactly. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description need not describe return values, and it covers the operation, the default, and the guarded failure cases. It is nearly complete for a simple mutation tool; only the result/state after a move is left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are fully documented in the schema. The description's note that overwrite defaults to false duplicates the schema, and it adds no syntax or format details for from/to beyond what the schema already states. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (move/rename) and resource (file or folder) and even names the underlying protocol (WebDAV MOVE). It does not distinguish itself from sibling tools such as delete or write_file, but the operation is unambiguous on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'or rename' phrasing implicitly tells the agent that renaming is done through this same call rather than a separate tool, and the caveats hint at invalid uses. However, no alternatives (e.g., delete, write_file) are named and there is no explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from Nextcloud. Text is returned as UTF-8. Binary files are refused unless encoding is base64. Files larger than the server read limit are refused rather than truncated.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to the Nextcloud files root. | |
| encoding | No | Omit for UTF-8 text. Pass "base64" for binary files. Text mode refuses binary payloads. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds real value on top: output encoding is UTF-8, binary is refused unless base64 is passed, and oversized files fail rather than truncate. It does not cover permission/auth failures or missing-path behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action, each carrying distinct information (encoding, binary handling, size failure mode) with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description responsibly states the return encoding and the two failure modes. It is nearly complete for a two-parameter read tool, though error signaling for bad paths or permissions is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter context by linking the encoding enum to content type ('binary files are refused unless encoding is base64'), clarifying the interaction beyond the per-parameter schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource ('Read a file from Nextcloud') with clear scope about what content is returned. It implicitly separates itself from write_file, but does not distinguish itself from stat, list_directory, or search, which an agent could confuse for content reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the description explains the encoding condition for binary files but never says when to prefer this over stat (metadata) or search (finding files). No explicit when-not or alternative routing is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search file and folder names with Nextcloud WebDAV SEARCH (RFC 5323) on /remote.php/dav/. This is a filename substring match inside one folder scope (default: the user's files), not full-text content search. The server must allow SEARCH. Results are capped.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Folder to search under, relative to the files root. Omit for the whole files tree. | |
| limit | No | Maximum results. Default 25. | |
| query | Yes | Filename substring. % _ and \ are removed so they are not LIKE wildcards. This does not search file contents. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing a real prerequisite ('the server must allow SEARCH') and a behavioral quirk ('results are capped'), which an agent needs to know before trusting an empty result set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the identifying mechanism and the key negative distinction front-loaded, no filler. The trailing 'Results are capped' is slightly vague and partially redundant with the schema's maximum of 100, which keeps it just under a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter, no-output-schema read tool the coverage is adequate: safety comes from annotations and parameters from the schema. However, it omits what a result actually contains (paths, names, properties?) and how the cap interacts with discovery, leaving an agent to infer the return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so path, limit and query are all already documented at the field level, including the wildcard stripping and the 'does not search file contents' note. The description only echoes the folder-scope and cap concepts, adding no syntax or format detail the schema lacks; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (search file and folder names) plus the exact mechanism (WebDAV SEARCH RFC 5323 on /remote.php/dav/) and scope (one folder). It explicitly contrasts with the nearest confusion risk — 'not full-text content search' — so an agent can separate it from read_file or list_directory without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use: filename substring match within one folder scope, defaulting to the user's files. It rules out content search, but never names a sibling it competes with (e.g. list_directory for browsing vs this for targeted lookup), so the routing guidance is contextual rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for one file or folder (name, size, type, etag, file id, modified time) via WebDAV PROPFIND. This is the file-info tool.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File or folder path relative to the Nextcloud files root. Empty string is the root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds useful context by naming the WebDAV PROPFIND mechanism and the returned metadata fields, but goes no further (no auth/rate caveats, no return-format detail). With annotations carrying the behavioral burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core purpose front-loaded, and the returned-field list earns its place. The trailing 'This is the file-info tool' is somewhat redundant given the name, but overall it is tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with annotations covering safety and no output schema, the description supplies the return fields an agent would otherwise lack. Nothing critical for invocation appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter and schema description coverage is 100%, so the schema fully documents the path argument including the empty-string-is-root case. The description adds nothing beyond this, so baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get metadata') and resource ('one file or folder') and enumerates the returned fields. 'One file' distinguishes it from the sibling list_directory, so an agent can route correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Placement of 'one file or folder' implies singular stat-ing versus a directory listing, and 'This is the file-info tool' reinforces intent. However, no explicit when/when-not guidance or named alternatives (e.g. list_directory, read_file) are provided, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or upload a file over WebDAV PUT. Refuses to overwrite an existing file unless overwrite is true. Set parents true to create missing parent folders. Does not delete anything else.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Destination path relative to the Nextcloud files root. | |
| content | Yes | File contents. UTF-8 text, or base64 when encoding is base64. | |
| parents | No | Create missing parent folders. Default false. | |
| encoding | No | utf8 (default) or base64. | |
| overwrite | No | Replace an existing file. Default false. | |
| contentType | No | Optional Content-Type. Defaults to text/plain or application/octet-stream. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description usefully narrows that destructiveness: the only mutation is an overwrite of the target file, gated behind overwrite=true, and 'Does not delete anything else.' That scope-limiting detail is real added value beyond the annotation flags. It stops short of describing failure modes or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action, then the two guard conditions and the non-effect. Every sentence carries information and none is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter write tool with no output schema, the description covers the important behavioral edge cases (overwrite refusal, auto-parent creation, no other deletions). It omits auth requirements and error/return behavior, but the essentials for correct invocation are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so path, content, parents, encoding, overwrite, and contentType are all already documented in the schema. The description restates the parents and overwrite semantics without adding new syntax, format, or constraint detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create or upload a file') plus the transport ('over WebDAV PUT'), which immediately separates it from siblings like mkdir, move, read_file, and delete. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives conditional guidance on parameter behavior (overwrite must be true to replace, parents true to create folders), but never says when to choose this tool over alternatives or states prerequisites/authentication needs. Usage is implied rather than explicitly framed as when-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_share_linkdeletelist_directorymkdirmoveread_filesearchstatwrite_fileScored across 9 tools
Each tool targets a clearly distinct file-system operation: stat for metadata, list_directory for listing, read_file/write_file for content, mkdir for folders, move/delete for lifecycle changes, create_share_link for sharing, and search for filename lookup. The descriptions explicitly distinguish overlapping-seeming tools, such as search being filename-only and stat being the file-info tool.
Most names use recognizable verb_noun or verb forms (list_directory, read_file, write_file, create_share_link), with conventional Unix-like exceptions such as stat, mkdir, move, delete, and search. The set is readable and predictable, but not a uniform verb_noun convention throughout.
Nine tools is well-scoped for a Nextcloud file operations server, covering the essential file/folder lifecycle and sharing actions without obvious filler. Each tool appears to earn its place in the surface.
Core CRUD/lifecycle operations are covered: stat, list, read, write, mkdir, move, delete, and create_share_link. Minor gaps exist around share-link management (listing or revoking links) and possibly copy operations, but agents can work around these or use WebDAV behavior for common file workflows.
Cloud file relay: chunked uploads, folders, share links, inline text reads, ZIP packing.
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
