Skip to main content
Glama
Huoshui File Search

Huoshui File Search

by huoshuiai42

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

This server is available in the Model Context Protocol Registry. Install it using your MCP client.

mcp-name: io.github.huoshuiai42/huoshui-file-search

uvx huoshui-file-search

From Source

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

Usage

As a Desktop Extension (DXT)

  1. Install the extension via your DXT-compatible application (e.g., Claude Desktop)

  2. The extension will be automatically configured and ready to use

  3. Use the search_files tool 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 string

  • path (optional): Directory to limit search scope

  • case_sensitive (optional): Enable case-sensitive search (default: false)

  • regex (optional): Regex pattern to filter results by filename

  • sort_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:movie

  • Filename search: kMDItemFSName == "*.py" - finds Python files

  • Combined 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:

  1. No files match both criteria

  2. The syntax needs adjustment (try 寻找工程车 AND kind:movie)

  3. Spotlight hasn't indexed the files yet

Examples

{
  "query": "document.pdf"
}

Search in Specific Directory

{
  "query": "*.txt",
  "path": "/Users/username/Documents"
}
{
  "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 scope

  • default_limit: Default maximum number of search results

  • enable_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 file

Testing Locally

  1. Install dependencies:

    uv sync
  2. Run the server:

    uv run python -m server

    Or after publishing to PyPI:

    uvx huoshui-file-search
  3. The server will communicate via stdio according to the MCP protocol

Publishing to PyPI

  1. Build the package:

    uv build
  2. Upload 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:

  1. Fork the repository

  2. Create a feature branch

  3. Add tests for new functionality

  4. Submit a pull request

Support

For issues and feature requests, please visit: https://github.com/huoshui/huoshui-file-search/issues

Available Tools

1 tool
search_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

    B3.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of ambiguity or confusion between tools.

    Naming Consistency5/5

    With a single tool, the naming is inherently consistent and follows a clear verb_noun pattern.

    Tool Count3/5

    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.

    Completeness5/5

    The tool provides file searching with filtering options, which fully covers the stated purpose of the server without obvious gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      15
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides fast file searching across Windows, macOS, and Linux using platform-native tools like Everything SDK, mdfind, and locate.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables instant file searches on Windows using Everything's native SDK, supporting advanced filters, duplicate detection, and content search through MCP tools.
      6
      MIT