Claude MarketplacesSubmit
huoshuiai42 avatar

Huoshui File Search

huoshuiai42/huoshui-file-search

Wraps macOS Spotlight's mdfind command to let Claude search your filesystem with the same power you'd get from the terminal. Exposes a single search_files tool that takes queries in Spotlight syntax (kind:pdf, kMDItemFSName wildcards, date filters) and returns JSON results. You can scope searches to specific directories, sort by name/size/date, apply regex filters to filenames, and limit result counts up to 1000. Built on FastMCP and only works on macOS 10.15 or later. Useful when you need Claude to locate files by content, metadata, or patterns without writing custom filesystem traversal code. The mdfind backend means searches are fast and leverage your existing Spotlight index.

tool
1
transport
STDIO
last updated
Sep 9, 2025
View on GitHub

Tools

1 tools

Public tool metadata for what this MCP can expose to an agent.

search_filesUse the `search_files` tool with various parameters

Use the `search_files` tool with various parameters

No parameter schema in public metadata yet.

Sponsors

Promote your product hereReach 125k+ visitors monthlyPromote your product hereReach 125k+ visitors monthlyAgent CaffeineSponsoredClose your lid, come back to finished workSnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthlyWaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthlyknobsSponsoredSee your site on any phone, any day, in any language

Readme

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

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-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)

View the full README on GitHub

Details

Repository
github.com/huoshuiai42/huoshui-file-search
Category
Search & Web Crawling
Package
huoshui-file-search
Transport
STDIO
Registry
MCP registry, active

More from huoshuiai42

Related Search & Web Crawling MCP servers

View all
1giskard09 avatarGiskard Searchgiskard09/giskard-searchPay-per-use web search for AI agents. Lightning invoice, Ed25519 signature, karma discounts.0stars
2ofershap avatarNpm Searchofershap/mcp-server-npmnpm search MCP — find packages, view details, compare, check downloads.0stars
3pipeworx-io avatarGoogle_search_consolepipeworx-io/mcp-google_search_consoleGoogle Search Console MCP Pack0stars
4pipeworx-io avatarTavilypipeworx-io/mcp-tavilyTavily MCP — wraps the Tavily API (tavily.com)0stars
5pjw2004 avatarJob Searchpjw2004/career-mcpSearch Korean job postings from JobKorea and Saramin by company name0stars
6tbrajkovic avatarFixatia Property Searchtbrajkovic/fixatiaSearch real estate auction properties across Europe with filtering by country, price, and ROI.0stars