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., "@Pathgrove find PDF invoices in my Documents from the last 7 days"
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.
Give your AI assistant a fast way to find your local files.
Pathgrove lets an MCP-compatible assistant find files without knowing their location first. It keeps a reusable filename index, so repeated searches do not have to walk every folder again. Search text inside files, inspect matches and get the paths you need through the same connection.
Ask your assistant:
Find invoice PDFs modified in the last seven days.
Find Python files containing
API_BASE_URL.Show me a preview of
annual-report.txt.
Runs locally on Windows, Linux and macOS. You choose the search folders. Pathgrove needs no hosted search service or API key; your MCP client controls what is sent to its model.
On a physical Mac mini M1 with about four million indexed entries, repeated filename searches returned these results:
Search | Fresh filesystem scan | Pathgrove MCP | Speed-up |
| 77.06 seconds | 64 milliseconds | 1,196× |
Broad substring | 77.65 seconds | 2.39 seconds | 32× |
Five trials per query, with identical ordered first-50 result pages checked each time. The comparison is against a fresh Python os.scandir traversal, using a warmed filename index. Indexing and startup are excluded; it is not a comparison against Everything or Spotlight. These measurements describe the recorded baseline, before the later indexing optimizations. Method and raw data →
The first index costs time: that Mac traversal took 17.2 minutes, and inaccessible paths still limited coverage. Start with your project or document folders. Optimized Windows full-drive completion is estimated at about 75 minutes, not measured to completion. Windows measurements and estimate →
Related MCP server: carrel
Requires Python 3.10+, Git and uv. See the SQLite requirements. Version 0.1.0 is available from source; it is not published to PyPI.
git clone https://github.com/elis132/pathgrove-mcp.git
cd pathgrove-mcp
uv sync --frozenAdd this to an MCP client that uses mcpServers configuration:
{
"mcpServers": {
"pathgrove": {
"command": "uv",
"args": ["run", "--directory", "<ABSOLUTE_CHECKOUT_PATH>", "--frozen", "pathgrove"],
"env": {
"PATHGROVE_ROOTS": "[\"<ABSOLUTE_SEARCH_ROOT>\"]"
}
}
}
}Replace <ABSOLUTE_CHECKOUT_PATH> with the directory you cloned, and <ABSOLUTE_SEARCH_ROOT> with an existing folder you want to search. Use your own absolute paths. Forward slashes work on Windows too, avoiding nested backslash escaping. You can put multiple roots in the JSON-encoded array. If the client cannot find uv, use its absolute executable path.
Restart your MCP client and ask it to find a file. Initial indexing runs in the background; committed batches become searchable before it finishes. Keep the server running for filesystem updates.
Task | Tool |
Find files by name, path, extension, size or date |
|
Search literal text, even before the index finishes |
|
Find file categories or recent changes |
|
Preview a file or inspect its metadata |
|
Count indexed matches or check index health |
|
Examples of filename queries:
invoice ext:pdf dm:last7days
"annual report" !draft
ext:py content:"API_BASE_URL"Search stays inside your configured roots and respects normal filesystem permissions. Links are not followed.
The index stores names, paths and metadata. Text is read from disk per query; PDF/Word extraction and OCR are not included.
Building indexes, inaccessible files and query budgets can produce partial results. A partial miss does not prove absence. The tools report these limits explicitly.
CI tests Python 3.10 and 3.14 across Linux, Windows and ARM/Intel macOS. Linux tests, lint and package builds use Ubicloud (ubicloud-standard-2); Windows and macOS use native GitHub-hosted runners. Forks need the Ubicloud app connected to run those Linux jobs.
Get count and size statistics for files matching a query.
Fast way to understand the scope of a query without listing every file. Optionally breaks down by extension for a high-level overview.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that results are a fast approximation/overview rather than exact enumeration, which is useful, but it does not say whether counts are exact or estimated, nor how large a query it handles well.
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, front-loaded with the core action and followed by the rationale. No filler; only slight redundancy between 'statistics' and the second line.
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?
An output schema exists so return values need not be explained, and annotations cover safety. Purpose, scope and result shape are adequately conveyed; the only real gap is the accuracy of counts under the sampling mentioned in the 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?
The description mirrors both optional behaviors ('count and size', 'breaks down by extension') corresponding to include_size and breakdown_by_extension, but adds no syntax or format detail for the query parameter. With declared schema coverage at 0%, this does not fully compensate, though the description at least signals what the optionals toggle.
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?
A specific verb and resource ('count and size statistics for files matching a query') tells the agent exactly what is produced. The clause 'without listing every file' implicitly distinguishes it from pathgrove_search, though no sibling is named explicitly.
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?
'Fast way to understand the scope of a query without listing every file' gives a clear use context and implies the alternative it replaces. It stops short of naming pathgrove_search or stating when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed metadata and optional content preview for specific files.
Returns: full path, size, dates, type, permissions, hidden status. For directories: item count, subdirectories, file listing. For text files with preview_lines > 0: first N lines of content.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 covered by structured data. The description adds real value in spelling out what is returned for files versus directories and the conditional nature of the preview. It says nothing about behavior for nonexistent paths, permission-denied cases, or partial failures across multiple paths, which is where an agent would still be guessing.
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?
Front-loaded with the core action in the first sentence, then a compact structured breakdown of returns. The 'Returns:' block is informative rather than filler, and there is no repetition, though it partially duplicates what the output schema already conveys.
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 an output schema and full annotation coverage, the description's remaining burden is small and it meets most of it: scope, return shapes, and preview behavior are all covered. The missing piece is failure behavior for invalid or inaccessible paths in a batch call.
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?
Reported schema coverage is 0%, although the schema does carry inline descriptions and numeric bounds for both fields. The description contributes one genuinely non-obvious semantic: preview content is only produced for text files when preview_lines > 0, which the schema does not state. It adds nothing about the 1-20 path limit or the batch semantics of passing multiple paths.
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: get metadata plus optional content preview for specific files. It clearly separates metadata inspection from the search-oriented siblings (pathgrove_search, pathgrove_search_content), though it never names an alternative, so the differentiation is inferred rather than explicit.
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 only implied: an agent can infer this is for inspecting known paths rather than discovering them. There is no explicit when-to-use or when-not-to-use guidance, and no routing to the search siblings for the case where paths are not known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files modified within a recent time period.
Ideal for discovering what changed in a project, tracking recent downloads, finding today's log files, etc. Sorted newest-first.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact beyond that – results are sorted newest-first – but says nothing about truncation by max_results, recursion into subdirectories, or what happens when the period yields nothing.
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 plus a one-line ordering note; the core capability is front-loaded in the first sentence and nothing is padded. The trailing newline fragment is slightly awkward but harmless.
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?
An output schema exists, so return-value explanation is not required, and the annotations cover safety. Still missing for a discovery tool: whether the search is recursive, how max_results truncation is signalled, and how it relates to the six sibling search tools – an agent choosing among them gets no routing help here.
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?
The reported coverage of 0% applies to the wrapped top-level 'params' object, but the nested schema does document path, query, period, extensions, and max_results in detail, and the description correctly frames the tool around the period concept. The description does not itself restate period formats or extension syntax, which is acceptable given the nested schema carries that load, though it could have warned that path defaults to empty (likely current directory).
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 ('Find files modified within a recent time period') plus the result ordering ('Sorted newest-first'), so an agent knows exactly what kind of result set to expect. It does not explicitly contrast itself with siblings like pathgrove_search or pathgrove_search_by_type, which is the only thing keeping it from a 5.
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 'Ideal for discovering what changed in a project, tracking recent downloads, finding today's log files' line gives concrete usage scenarios, which is real guidance. However, it offers no when-not conditions and never names an alternative sibling tool for time-agnostic searching, so the agent must infer the boundary with pathgrove_search itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report independent index readiness, configured roots and last scan errors.
A building index may serve cached rows while reconciliation is in progress. This tool does not trigger a full rescan or require any external application.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, closed-world and non-destructive semantics, so the bar is lower. The description still adds real behavioral context beyond them: a building index may serve cached rows during reconciliation, and the call does not trigger a rescan or require an external application. That tells the agent what state the reported data may be in, which annotations cannot express.
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 reported content front-loaded and the caveat second. Every sentence carries information; a slight tightening is possible but there is no padding.
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 an output schema present, the description does not need to enumerate return values. It covers what is reported plus the key caveat about mid-reconciliation results, leaving little an agent would need before calling it.
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?
The tool takes zero parameters, so the baseline is 4. Nothing about parameter behavior is missing or ambiguous.
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?
The description states a specific verb and resource: reports index readiness, configured roots, and last scan errors. It is clearly distinguishable from the search siblings, though it never names them explicitly. The purpose is unambiguous 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?
Usage is only implied: the reconciliation caveat hints this tool is the way to check index health while a scan is running. There is no explicit when-to-use guidance, no mention of when to prefer it over pathgrove_count_stats or the search tools, and no stated prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search configured roots using our own SQLite filename/metadata index.
No external application, background search service or GUI is required. The first build may take time; pathgrove_index_status reports progress.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful operational context that the first index build may take time and that progress is reported by pathgrove_index_status, but it does not discuss result completeness, pagination behavior, or search coverage limits.
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 primary action and key operational caveat. There is no unnecessary repetition, though it could be tightened slightly.
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 search tool with annotations and an output schema, the description covers the core operation and the first-build latency caveat. However, given the many closely related search siblings, it lacks routing guidance that would help an agent decide between filename/metadata search, content search, type search, and recent-file search.
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?
The description itself adds no parameter guidance. The nested input schema is unusually rich, documenting query syntax, sort options, pagination, regex, whole-word, and case matching, so the schema carries most parameter semantics. The top-level coverage signal is low, but the visible child-field descriptions compensate substantially.
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 action, searching configured roots, and identifies the mechanism as an SQLite filename/metadata index. It does not distinguish itself from several siblings such as pathgrove_search_content, pathgrove_search_by_type, or pathgrove_find_recent, beyond referencing pathgrove_index_status for build progress.
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: search filename/metadata via the local index, and use pathgrove_index_status to monitor first-build progress. There is no explicit guidance on when to choose this over sibling search tools or when another tool is more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for files by type category.
Categories: audio, video, image, document, code, archive, executable, font, 3d, data. Each maps to a curated list of file extensions.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful context that categories map to curated extension lists, but it does not disclose recursion behavior, hidden-file handling, or permission assumptions.
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?
The description is two short sentences, front-loads the tool purpose, and then supplies the category enumeration. Every sentence adds value with no 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?
An output schema exists, so return values need not be explained, and annotations cover safety behavior. However, the description remains minimal for a search tool with several sibling alternatives and undocumented search parameters, so an agent lacks routing guidance and operational context.
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?
Against the reported 0% schema description coverage, the description only clarifies the file_type categories and their extension-list mapping. It does not document path scoping, query filtering, sort behavior, or max_results semantics.
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?
The description states a specific verb and resource: 'Search for files by type category.' It clearly signals the tool's function, but it does not explicitly differentiate it from siblings such as pathgrove_search or pathgrove_find_recent.
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 offers no explicit guidance on when to use this tool versus alternatives like pathgrove_search or pathgrove_search_content. Usage can be inferred from the category list, but there are no stated exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search text directly on disk without waiting for the filename index.
Recurses within configured roots; returns matches in traversal order. UTF-8 and BOM-marked UTF-16/32 are supported. Time/read/file limits and skipped files are explicitly reported. No date ordering or global pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds real value beyond them: traversal-order results, UTF-8/UTF-16/32 BOM handling, that time/read/file limits and skipped files are explicitly reported, and that there is no date ordering or global pagination. That last point is exactly the kind of surprise-surfacing detail annotations cannot carry.
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?
Short and front-loaded, with the core differentiator in the first sentence and the caveats after. The line-broken formatting is slightly awkward but no sentence is padding.
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 an output schema present, return shape need not be described, and the notable behavioral caveats (limits, skipped files, no pagination) are covered. The remaining gap is search-semantics detail for the schema's undocumented parameters.
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?
Reported schema description coverage is 0%, so the description carries the burden, and it only partially does: it explains encoding support and the presence of limits (relevant to extensions and max_results) but says nothing about path scoping, recursive behavior, match_case, or match_whole_word semantics. Useful but not compensatory.
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?
The first sentence states a specific verb and resource (search text inside file contents, not filenames) and implicitly contrasts with the filename-index sibling. It stops short of naming siblings like pathgrove_search, so an agent must infer the routing rather than being told.
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?
'Without waiting for the filename index' implies the use case (content search when the index is stale or irrelevant), but there is no explicit when-not guidance and no sibling is named as the alternative for filename-based lookup. Usage is implied rather than stated.
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.0pathgrove_count_statspathgrove_file_detailspathgrove_find_recentpathgrove_index_statuspathgrove_searchpathgrove_search_by_typepathgrove_search_contentScored across 7 tools
The tools mostly have distinct purposes: indexed filename search, direct content search, type-based search, recent-file search, details, stats, and index status. Some boundary overlap exists between general search, type search, and recent search, but the descriptions make the intended distinctions reasonably clear.
All tools use a consistent pathgrove_ prefix and snake_case, which makes the set predictable. The suffixes mix action-oriented verbs (search, find_recent) with noun/status forms (index_status, file_details, count_stats), but this is readable and mostly coherent.
Seven tools is well-scoped for a file search and indexing server. Each tool covers a distinct workflow: indexed search, content search, type filtering, recency, details, stats, and index readiness.
The surface covers core file discovery, content search, metadata inspection, statistics, and index status. Minor gaps remain around explicitly configuring roots, triggering a rebuild/rescan, or retrieving full file contents, but the main search workflows are represented.
Securely search and manage workspace context files for AI agents and teams.
Agentic search over your Dewey document collections from any MCP-compatible client.
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
