Huoshui File Search

Provides fast macOS file search using Spotlight with configurable filters and clean JSON responses.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

Huoshui File Search is an MCP server that enables fast macOS file searching using the native Spotlight index. You can access it through MCP clients to perform configurable searches and receive clean, structured results, all while leveraging the macOS search capabilities of mdfind.

How to use

You interact with the Huoshui File Search MCP server through an MCP client. Start by launching the server in stdio mode, then send search requests to perform file queries across your macOS filesystem. You can apply filters such as restricting the search path, enabling case sensitivity, applying a regular expression on filenames, and choosing how results are sorted. The server responds with a clean JSON structure containing the matching file paths and metadata.

How to install

Prerequisites you need before installation include a macOS system (macOS 10.15 or later) and access to Python-based tooling. You should also have a suitable MCP client installed to communicate with servers over stdio or HTTP.

Step by step installation options are provided below. Choose the method that best fits your workflow.

From MCP Registry (Recommended) install using your MCP client.

uvx huoshui-file-search

From Source

If you prefer building from source, clone the repository and install dependencies locally before running the server.

git clone https://github.com/huoshui/huoshui-file-search.git
cd huoshui-file-search
uv sync

Notes on running locally after installation

After dependencies are installed, start or run the server in stdio mode so it communicates via the MCP protocol. The final, explicit run command shown for development is used to execute the server locally.

Run command example used during development:

uv run python -m server

Available tools

search_files

Executes a file search using the MCP server with configurable parameters such as the query, path, case sensitivity, regex filtering, sort order, and limit.

FileSearchParams

A structured parameter container that defines the search inputs, including query, path, case_sensitive, regex, sort_by, and limit.