Everything Search

Everything Search MCP Server

[PyPI] [CI]

An MCP server that provides fast file searching capabilities across Windows, macOS, and Linux. On Windows, it uses the Everything SDK. On macOS, it uses the built-in mdfind command. On Linux, it uses the locate/plocate command.

Requires Python 3.10+. Since 0.3.0 the server is built on the MCP Python SDK 2.x. See CHANGELOG.md for release notes.

Tools

search

Search for files and folders across your system. The search capabilities and syntax support vary by platform:

• Windows: Full Everything SDK features (see syntax guide below)
• macOS: Basic filename and content search using Spotlight database
• Linux: Basic filename search using locate database

Arguments are grouped into a base object (all platforms) and a platform-specific object. The server advertises only the current platform's object in its tool schema.

base (required):

• query (required): Search query string. See the syntax guide.
• max_results (optional): Maximum number of results to return (default: 100, range: 1-1000)

windows_params (optional, Windows only):

• match_path: Match against full path instead of filename only (default: false)
• match_case: Enable case-sensitive search (default: false)
• match_whole_word: Match whole words only (default: false)
• match_regex: Enable regex search (default: false)
• sort_by: Sort order for results (default: 1). Available options:

  - 1: Sort by filename (A to Z)  - 2: Sort by filename (Z to A)  - 3: Sort by path (A to Z)  - 4: Sort by path (Z to A)  - 5: Sort by size (smallest first)  - 6: Sort by size (largest first)  - 7: Sort by extension (A to Z)  - 8: Sort by extension (Z to A)  - 11: Sort by creation date (oldest first)  - 12: Sort by creation date (newest first)  - 13: Sort by modification date (oldest first)  - 14: Sort by modification date (newest first)

mac_params (optional, macOS only):

• search_directory: Limit the search to a directory (mdfind -onlyin). ~ is expanded; the directory must exist.
• literal_query: Treat the query as a literal Spotlight query string (-literal)
• interpret_query: Interpret the query as if typed in the Spotlight menu (-interpret)
• live_updates: Not supported. mdfind -live never exits, so setting it returns an error.

By default the query is a filename search (mdfind -name). Setting literal_query or interpret_query passes the query to Spotlight as-is instead; such a query must not start with -, because mdfind would read it as an option.

linux_params (optional, Linux only):

• ignore_case: Case-insensitive search, -i (default: true)
• regex_search: Treat the query as a regular expression (default: false)
• existing_files: Only list files that still exist, -e (default: true)
• count_only: Return only the number of matches, -c (default: false)

Examples:

{  "base": {"query": "*.py", "max_results": 50},  "windows_params": {"sort_by": 6}}

{  "base": {"query": "ext:py datemodified:today", "max_results": 10}}

{  "base": {"query": "ENABLE", "max_results": 50},  "mac_params": {"search_directory": "/Users/me/code/myrepo"}}

Each result includes:

• Path: full path
• Filename: name, with the extension in parentheses when present
• Size: size in bytes
• Created, Modified, Accessed: timestamps, or N/A when unavailable

If a search fails (invalid arguments, Everything not running, a search command taking longer than 30 seconds, and so on), the tool returns an error result (isError: true) whose text starts with Search failed:.

On Windows, if some matches cannot be read from Everything (for example a file with a corrupt timestamp), the readable results are returned and the output ends with Warning: N matching result(s) could not be read and were omitted.

Search Syntax Guide

For detailed information about the search syntax supported on each platform (Windows, macOS, and Linux), please see SEARCH_SYNTAX.md.

Prerequisites

Windows

1. Everything search utility:
   • Download and install from https://www.voidtools.com/
   • Make sure the Everything service is running
2. Everything SDK:
   • Download from https://www.voidtools.com/support/everything/sdk/
   • Extract the SDK files to a location on your system
   • The same SDK DLL (Everything64.dll) also works with Everything 1.5

Linux

1. Install and initialize the locate or plocate command:
   • Ubuntu/Debian: sudo apt-get install plocate or sudo apt-get install mlocate
   • Fedora: sudo dnf install mlocate
2. After installation, update the database:
   • For plocate: sudo updatedb
   • For mlocate: sudo /etc/cron.daily/mlocate

macOS

No additional setup required. The server uses the built-in mdfind command.

Installation

Using uv (recommended)

When using uv no specific installation is needed. We will use uvx to directly run mcp-server-everything-search.

Upgrading from 0.2.x: uvx may keep using a cached 0.2.1, which fails to start with the current MCP SDK ('Server' object has no attribute 'list_resources', see #39). Run it once with the latest version to refresh the cache:

uvx mcp-server-everything-search@latest

Using PIP

Alternatively you can install mcp-server-everything-search via pip:

pip install -U mcp-server-everything-search

After installation, you can run it as a script using:

python -m mcp_server_everything_search

Configuration

Windows

Set EVERYTHING_SDK_PATH to the full path of Everything64.dll from the Everything SDK. It is required: the server stops at startup with an error naming the variable if it is unset or does not point to a file.

EVERYTHING_SDK_PATH=C:\path\to\Everything-SDK\dll\Everything64.dll

Linux and macOS

No additional configuration required.

Tool name

The tool is called search by default. If that name collides with another MCP server's tool in your client, rename it:

EVERYTHING_SEARCH_TOOL_NAME=everything_search

The name may use letters, digits, _ and - (1-64 characters). An invalid value stops the server at startup.

Usage with Claude Code

Windows:

claude mcp add everything-search -e EVERYTHING_SDK_PATH="C:\path\to\Everything-SDK\dll\Everything64.dll" -- uvx mcp-server-everything-search

Linux and macOS:

claude mcp add everything-search -- uvx mcp-server-everything-search

Usage with Claude Desktop

Add one of these configurations to your claude_desktop_config.json based on your platform:

{  "mcpServers": {    "everything-search": {      "command": "uvx",      "args": ["mcp-server-everything-search"],      "env": {        "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"      }    }  }}

{  "mcpServers": {    "everything-search": {      "command": "python",      "args": ["-m", "mcp_server_everything_search"],      "env": {        "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"      }    }  }}

{  "mcpServers": {    "everything-search": {      "command": "uvx",      "args": ["mcp-server-everything-search"]    }  }}

{  "mcpServers": {    "everything-search": {      "command": "python",      "args": ["-m", "mcp_server_everything_search"]    }  }}

Debugging

You can use the MCP inspector to debug the server. For uvx installations:

npx @modelcontextprotocol/inspector uvx mcp-server-everything-search

Or if you've installed the package in a specific directory or are developing on it:

git clone https://github.com/mamertofabian/mcp-everything-search.gitcd mcp-everything-searchnpx @modelcontextprotocol/inspector uv run mcp-server-everything-search

To view server logs:

Linux/macOS:

tail -f ~/.config/Claude/logs/mcp*.log

Windows (PowerShell):

Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait

Development

If you are doing local development, there are two ways to test your changes:

1. Run the MCP inspector to test your changes. See Debugging for run instructions.

2. Test using the Claude desktop app. Add the following to your claude_desktop_config.json:

{  "mcpServers": {    "everything-search": {      "command": "uv",      "args": [        "--directory",        "/path/to/mcp-everything-search",        "run",        "mcp-server-everything-search"      ],      "env": {        "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"      }    }  }}

Tests and checks

uv run pytestuv run ruff checkuv run pyright

CI runs the tests on Windows, macOS and Linux (Python 3.10 and 3.13). Code changes are planned as MAID manifests in manifests/; see CLAUDE.md/AGENTS.md and run scripts/maid validate before opening a pull request.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by voidtools (the creators of Everything search utility). This is an independent project that utilizes the publicly available Everything SDK.