Everything Search MCP Server

Everything Search MCP 服务

一个 MCP 服务，可在 Windows、macOS 和 Linux 上快速搜索文件。在 Windows 上，它使用 Everything SDK；在 macOS 上，它使用内置的 mdfind 命令；在 Linux 上，它使用 locate/plocate 命令。

需要 Python 3.10 或更高版本。自 0.3.0 起，该服务基于 MCP Python SDK 2.x 构建。发行说明请参阅 CHANGELOG.md。

工具

search

在系统中搜索文件和文件夹。各平台支持的搜索功能和语法有所不同：

• Windows：支持完整的 Everything SDK 功能（见下方语法指南）
• macOS：使用 Spotlight 数据库进行基本的文件名和内容搜索
• Linux：使用 locate 数据库进行基本的文件名搜索

参数分为 base 对象（适用于所有平台）和平台专属对象。该服务只会在工具架构中公布当前平台对应的对象。

base（必填）：

• query（必填）：搜索查询字符串。请参阅语法指南。
• max_results（可选）：返回结果的数量上限（默认值：100，范围：1-1000）

windows_params（可选，仅限 Windows）：

• match_path：匹配完整路径，而不仅是文件名（默认值：false）
• match_case：启用区分大小写搜索（默认值：false）
• match_whole_word：仅匹配完整单词（默认值：false）
• match_regex：启用正则表达式搜索（默认值：false）
• sort_by：结果的排序顺序（默认值：1）。可用选项：

  - 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（可选，仅限 macOS）：

• search_directory：将搜索范围限定在某个目录中（mdfind -onlyin）。~ 会展开；该目录必须存在。
• literal_query：将查询视为字面形式的 Spotlight 查询字符串（-literal）
• interpret_query：将查询按在 Spotlight 菜单中输入的方式进行解释（-interpret）
• live_updates：不支持。mdfind -live 不会退出，因此设置该参数会返回错误。

默认情况下，查询用于搜索文件名（mdfind -name）。设置 literal_query 或 interpret_query 会将查询原样传递给 Spotlight；这类查询不能以 - 开头，否则 mdfind 会将其视为选项。

linux_params（可选，仅限 Linux）：

• ignore_case：不区分大小写搜索，-i（默认值：true）
• regex_search：将查询视为正则表达式（默认值：false）
• existing_files：仅列出仍然存在的文件，-e（默认值：true）
• count_only：仅返回匹配数量，-c（默认值：false）

示例：

{
  "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"}
}

每个结果都包含：

• Path：完整路径
• Filename：名称；如果有扩展名，则在括号中显示
• Size：以字节为单位的大小
• Created、Modified、Accessed：时间戳；如果不可用，则显示 N/A

如果搜索失败（例如参数无效、Everything 未运行，或搜索命令耗时超过 30 秒），工具会返回错误结果（isError: true），其文本以 Search failed: 开头。

在 Windows 上，如果无法从 Everything 读取部分匹配结果（例如文件的时间戳已损坏），则会返回可读取的结果，并在输出末尾显示 Warning: N matching result(s) could not be read and were omitted.。

搜索语法指南

有关各平台（Windows、macOS 和 Linux）所支持搜索语法的详细信息，请参阅 SEARCH_SYNTAX.md。

前置条件

Windows

1. Everything 搜索工具：
   • 从 https://www.voidtools.com/ 下载并安装
   • 确保 Everything 服务正在运行
2. Everything SDK：
   • 从 https://www.voidtools.com/support/everything/sdk/ 下载
   • 将 SDK 文件解压到系统中的某个位置
   • 同一个 SDK DLL（Everything64.dll）也适用于 Everything 1.5

Linux

1. 安装并初始化 locate 或 plocate 命令：
   • Ubuntu/Debian：sudo apt-get install plocate 或 sudo apt-get install mlocate
   • Fedora：sudo dnf install mlocate
2. 安装后，更新数据库：
   • 对于 plocate：sudo updatedb
   • 对于 mlocate：sudo /etc/cron.daily/mlocate

macOS

无需额外设置。服务使用内置的 mdfind 命令。

安装

使用 uv（推荐）

使用 uv 时，无需进行特定安装。我们将使用 uvx 直接运行 mcp-server-everything-search。

从 0.2.x 升级： uvx 可能会继续使用缓存中的 0.2.1，导致其无法通过当前 MCP SDK 启动（'Server' object has no attribute 'list_resources'，参见 #39）。使用最新版本运行一次以刷新缓存：

uvx mcp-server-everything-search@latest

使用 PIP

或者，你也可以通过 pip 安装 mcp-server-everything-search：

pip install -U mcp-server-everything-search

安装后，可以通过以下方式将其作为脚本运行：

python -m mcp_server_everything_search

配置

Windows

将 EVERYTHING_SDK_PATH 设置为 Everything SDK 中 Everything64.dll 的完整路径。此项为必需：如果未设置该变量或其路径未指向文件，服务会在启动时停止，并报告该变量名称。

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

Linux 和 macOS

无需额外配置。

工具名称

默认情况下，工具名为 search。如果该名称与客户端中另一个 MCP 服务的工具名称冲突，请为其重命名：

EVERYTHING_SEARCH_TOOL_NAME=everything_search

名称可以包含字母、数字、_ 和 -（1–64 个字符）。如果值无效，服务会在启动时停止。

与 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 和 macOS：

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

与 Claude Desktop 配合使用

根据你的平台，将以下某个配置添加到 claude_desktop_config.json：

{
  "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"]
    }
  }
}

调试

你可以使用 MCP inspector 调试服务。对于 uvx 安装：

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

或者，如果你已将软件包安装到特定目录，或正在开发该软件包：

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

查看服务日志：

Linux/macOS：

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

Windows（PowerShell）：

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

开发

如果你正在进行本地开发，有两种方式可以测试更改：

1. 运行 MCP inspector 测试更改。运行说明请参阅调试。

2. 使用 Claude 桌面应用测试。将以下内容添加到 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"
      }
    }
  }
}

测试和检查

uv run pytest
uv run ruff check
uv run pyright

CI 会在 Windows、macOS 和 Linux 上运行测试（Python 3.10 和 3.13）。代码更改以 manifests/ 中的 MAID 清单形式规划；请参阅 CLAUDE.md/AGENTS.md，并在提交拉取请求前运行 scripts/maid validate。

许可证

此 MCP 服务采用 MIT License 授权。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。更多详情请参阅项目仓库中的 LICENSE 文件。

免责声明

本项目与 voidtools（Everything 搜索工具的开发者）无关联，未获得其认可或赞助。本项目为独立项目，使用公开提供的 Everything SDK。