Log inSubmit server
Huoshui File Search logo

Huoshui File Search

Searches macOS Spotlight indexes through MCP with path, regex, sorting, case, and result-limit controls.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Huoshui File Search

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "huoshui-file-search": {
      "command": "uvx",
      "args": [
        "huoshui-file-search"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 1 tools correctly (10d ago).

Overview

The huoshui-file-search MCP server exposes macOS Spotlight file search through the native `mdfind` command. Its search tool accepts a query plus optional path, case-sensitivity, regex, sorting, and result-limit filters, returning structured JSON. Reach for it when an agent needs to locate files on an indexed Mac; it requires macOS and does not support Windows or Linux.

Use cases

  • Search indexed Mac files by name or content
  • Restrict searches to a specific directory
  • Filter filenames with regular expressions
  • Sort and cap file-search results
  • Query files by Spotlight kind or date

Key features

  • macOS Spotlight search through native mdfind
  • Path-based search restriction
  • Case-sensitive matching
  • Filename regex filtering
  • Name, size, or date sorting
  • Configurable result limits

Tools1

What Huoshui File Search lets your agent do. Expand a tool for its parameters.

Verified live~265 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

8/8 checks healthy over the last 45d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 13d ago via OSV.dev · huoshui-file-search (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

Last commit1y agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed1Callable tools this server registers over MCP.
Directory activity3 viewsConfig copies, upvotes, and views on AllMCPs.

How Huoshui File Search works

What huoshui-file-search MCP server does

The huoshui-file-search MCP server lets MCP clients search files through macOS Spotlight. It uses the system’s native mdfind command rather than implementing a separate file index, so results depend on Spotlight indexing and search scope.

The primary operation is exposed as search_files. Its required query field accepts Spotlight query syntax, including plain text, file-kind filters, filename metadata expressions, combined conditions, and date-oriented searches. Optional parameters narrow or shape the result set:

  • path restricts the search to a directory.
  • case_sensitive enables case-sensitive matching and defaults to false.
  • regex filters result filenames with a regular expression.
  • sort_by accepts name, size, or date.
  • limit caps the number of results, with a default of 100 and a maximum of 1,000.

Responses use a JSON structure intended for consumption by MCP clients and agents.

How it works

A client sends the search parameters over MCP, and the server runs the corresponding Spotlight query through mdfind. For example, a query can look for a filename such as *.py, combine a term with kind:pdf, or request files modified today. The optional regular-expression filter is applied to filenames, while path, sorting, and result-limit settings control the returned matches.

Spotlight must have indexed the relevant files before they can be found. A query returning no results may indicate that indexing is incomplete, the path is outside Spotlight’s search scope, or the query syntax needs adjustment. Searches can time out after 30 seconds, particularly when they cover large areas; narrower paths and more specific queries can reduce that risk.

Setup and configuration

To run the huoshui-file-search MCP server, use macOS 10.15 or later, Python 3.10 or later, and the uv package manager. The package can be launched with uvx huoshui-file-search. From a source checkout, install dependencies with uv sync and start it with uv run python -m server. The server communicates over MCP using stdio.

The project is also published in the MCP Registry under io.github.huoshuiai42/huoshui-file-search. DXT-compatible applications can install the extension and configure it automatically through the extension manifest.

The DXT configuration supports allowed_directories for limiting search scope, default_limit for setting the default result count, and enable_logging for debug logging. These are extension configuration options rather than documented environment variables.

Limitations and notes

The huoshui-file-search MCP server is macOS-only; Windows and Linux are not supported. It also requires Spotlight indexing to be enabled and the mdfind command to be available. Files that are still being indexed, or directories excluded from Spotlight search, will not appear in results.

The query field follows Spotlight’s mdfind syntax, so agent-generated searches need to use compatible expressions. Combining terms with AND may be necessary when a plain juxtaposition does not produce the intended match. The maximum result limit is 1,000, and large searches may time out after approximately 30 seconds.

The repository is licensed under the MIT License. Its documented system interface is stdio, making it suitable for MCP clients that can launch local stdio servers, including DXT-compatible applications such as Claude Desktop.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Huoshui File Search

huoshui-file-search is an MCP server that connects AI clients to macOS Spotlight through the native `mdfind` command. Its main `search_files` tool accepts a query, optional path, case-sensitivity, regex, sorting, and result-limit parameters, then returns file-search results in structured JSON.

Install it with `uvx huoshui-file-search`, use its MCP Registry entry, or clone the source and run `uv sync`. DXT-compatible applications can install the extension through their normal extension workflow.

No, huoshui-file-search only works on macOS 10.15 or later. It depends on the native `mdfind` command and Spotlight indexing, so Windows and Linux are not supported.

Set the tool’s `path` parameter to the directory you want to search. You can also configure allowed directories through the DXT manifest and use `limit` to cap returned results.

Related MCP servers

All in File Systems All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHuoshui File Search AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/huoshui-file-search?style=directory)](https://allmcps.com/mcp/huoshui-file-search)
HTML Embed
<a href="https://allmcps.com/mcp/huoshui-file-search"><img src="https://allmcps.com/api/badge/huoshui-file-search?style=directory" alt="Huoshui File Search on AllMCPs" /></a>