Huoshui File Search
Allows searching files on macOS using the native Spotlight index, with support for query filters, case-sensitive search, regex filtering, sorting by name/size/date, and configurable result limits.
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., "@Huoshui File Search find pdf files containing invoice"
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.
Huoshui File Search
A Desktop Extension (DXT) that provides fast file search capabilities for macOS using the native mdfind command (Spotlight search).
⚠️ IMPORTANT: This extension only works on macOS systems. Windows and Linux are not supported.
Features
Fast file search using macOS Spotlight index
Multiple filtering options:
Path-based search restrictions
Case-sensitive/insensitive search
Regular expression matching
Sort results by name, size, or date
Configurable search limits
Clean JSON-structured responses
Built with FastMCP framework for optimal performance
Related MCP server: fd-mcp
Installation
From MCP Registry (Recommended)
This server is available in the Model Context Protocol Registry. Install it using your MCP client.
mcp-name: io.github.huoshuiai42/huoshui-file-search
Via PyPI (Recommended)
uvx huoshui-file-searchFrom Source
git clone https://github.com/huoshui/huoshui-file-search.git
cd huoshui-file-search
uv syncUsage
As a Desktop Extension (DXT)
Install the extension via your DXT-compatible application (e.g., Claude Desktop)
The extension will be automatically configured and ready to use
Use the
search_filestool with various parameters
Direct Usage
from server.main import search_files, FileSearchParams
# Basic search
params = FileSearchParams(query="report.pdf")
result = await search_files(None, params)
# Search with filters
params = FileSearchParams(
query="*.py",
path="/Users/username/Documents",
case_sensitive=True,
sort_by="size",
limit=50
)
result = await search_files(None, params)Tool Parameters
query(required): Search query stringpath(optional): Directory to limit search scopecase_sensitive(optional): Enable case-sensitive search (default: false)regex(optional): Regex pattern to filter results by filenamesort_by(optional): Sort results by 'name', 'size', or 'date'limit(optional): Maximum number of results (default: 100, max: 1000)
mdfind Query Syntax
The query parameter uses macOS Spotlight's mdfind syntax:
Simple text search:
report- finds files containing "report"File kind:
kind:pdf,kind:image,kind:movieFilename search:
kMDItemFSName == "*.py"- finds Python filesCombined queries:
invoice AND kind:pdf- finds PDF files containing "invoice"Date queries:
date:today,modified:this week
Note: If your query like '寻找工程车' kind:movie returns no results, it might mean:
No files match both criteria
The syntax needs adjustment (try
寻找工程车 AND kind:movie)Spotlight hasn't indexed the files yet
Examples
Basic File Search
{
"query": "document.pdf"
}Search in Specific Directory
{
"query": "*.txt",
"path": "/Users/username/Documents"
}Case-Sensitive Search
{
"query": "README",
"case_sensitive": true
}Search with Regex Filter
{
"query": "kind:text",
"regex": "log.*2024.*\\.txt$"
}Sorted and Limited Results
{
"query": "*.jpg",
"sort_by": "size",
"limit": 20
}Configuration
The extension supports user configuration through the DXT manifest:
allowed_directories: List of directories to limit search scopedefault_limit: Default maximum number of search resultsenable_logging: Enable debug logging
Development
Project Structure
huoshui-file-search/
├── manifest.json # DXT manifest file
├── server/ # MCP server implementation
│ ├── __init__.py
│ ├── __main__.py
│ └── main.py
├── pyproject.toml # Python package configuration
├── requirements.txt # Python dependencies
├── LICENSE # MIT License
└── README.md # This fileTesting Locally
Install dependencies:
uv syncRun the server:
uv run python -m serverOr after publishing to PyPI:
uvx huoshui-file-searchThe server will communicate via stdio according to the MCP protocol
Publishing to PyPI
Build the package:
uv buildUpload to PyPI:
uv publish
System Requirements
macOS 10.15 or later
Python 3.10 or later
uv package manager (install with:
curl -LsSf https://astral.sh/uv/install.sh | sh)Spotlight indexing enabled
Troubleshooting
"Platform not supported" Error
This extension only works on macOS. Ensure you're running it on a Mac.
"mdfind command not found" Error
Ensure Spotlight is enabled on your Mac. You can check this in System Preferences > Spotlight.
No Search Results
Spotlight may still be indexing new files
Check if the file path is included in Spotlight's search scope
Verify the search query syntax
Search Timeout
Large searches may timeout after 30 seconds. Try:
Limiting the search path
Using more specific queries
Reducing the result limit
License
MIT License - see LICENSE file for details
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request
Support
For issues and feature requests, please visit: https://github.com/huoshui/huoshui-file-search/issues
Available Tools
1 toolsearch_filesC
Search for files using macOS mdfind with filtering options
Inputs: params (required). Returns: Search result response
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no possibility of ambiguity or confusion between tools.
With a single tool, the naming is inherently consistent and follows a clear verb_noun pattern.
A single tool for a file search server is borderline; it feels thin but may be acceptable if the tool is comprehensive enough to cover all search needs.
The tool provides file searching with filtering options, which fully covers the stated purpose of the server without obvious gaps.
Related MCP Connectors
Search and read Apple developer documentation, HIG, and WWDC transcripts as Markdown.
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Find, read and reorganize files across Google Drive, OneDrive, SharePoint and Dropbox, with undo.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables instant file and folder searching on Windows using Everything's blazing-fast search engine, supporting powerful search syntax including wildcards, regex, size filters, date filters, and comprehensive file information retrieval.64 npm15MIT
- AlicenseNot gradedqualityDmaintenanceProvides fast file search capabilities using fd (a modern find alternative), enabling AI assistants to efficiently navigate codebases, search file contents with ripgrep, and execute commands on matched files.28 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceProvides fast file searching across Windows, macOS, and Linux using platform-native tools like Everything SDK, mdfind, and locate.MIT
- AlicenseNot gradedqualityDmaintenanceEnables instant file searches on Windows using Everything's native SDK, supporting advanced filters, duplicate detection, and content search through MCP tools.6MIT