Skip to main content
Glama
Nextcloud MCP Server

Nextcloud MCP Server

by stack74

Search files by name, type and date

nextcloud_search_files
Read-onlyIdempotent

Search Nextcloud files and folders by name, type, or modification date, or list recent changes to see what you were working on. Searches file names only, in one request.

Instructions

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "nextcloud_search_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoOnly search below this folder. Default: everything./
sortNonewest
typeNoRestrict to one kind of file.any
limitNo
queryNoWords or a '*' pattern to match in the file name. Case-insensitive.
offsetNoSkip this many results, for paging.
favorites_onlyNoOnly items the user marked as favorite.
modified_afterNoOnly items changed on/after this date (YYYY-MM-DD).
include_foldersNoInclude folders in the results (ignored when 'type' is set).
modified_beforeNoOnly items changed before this date (YYYY-MM-DD).
response_formatNo'markdown' for readable output, 'json' for structured datamarkdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.2

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds recursion scope and the empty-query behavior, but says nothing about result limits, paging past the default 30, or how many matches can be returned — relevant for a search tool with 200 max limit and 900+ offset range.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by tight labeled bullets for each filtering mode, with the critical sibling redirect as the closing line. Every sentence carries information; nothing is redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with no output schema it covers the high-value semantics well, including the default-result behavior when no query is given. It falls short on paging/result-size guidance and on sort/limit/offset behavior, which matter for broad recursive searches.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 82%, so the baseline is 3, and the description does partially exceed it by explaining wildcard syntax, multi-word AND matching, and the semantic mapping of type values (document = Word/ODT, spreadsheet = Excel/ODS/CSV). However it never mentions sort, limit, offset, favorites_only, include_folders, or response_format, which together are a large share of the 11 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find files and folders anywhere below a folder') plus scope ('anywhere below a folder, searched on the Nextcloud server'), and explicitly separates name search from content search by naming nextcloud_search_file_contents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use guidance for each mode (name, type, date) and an explicit exclusion: 'This searches names, not content. For words inside files use nextcloud_search_file_contents.' It also tells the agent what an empty 'query' means, which is the key routing decision versus a plain listing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.