Skip to content
Back to search

mcp-everything-search

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…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mamertofabian--mcp-everything-search/badge.svg)](/listings/mamertofabian--mcp-everything-search)

HTML

<a href="/listings/mamertofabian--mcp-everything-search"><img src="/api/listings/mamertofabian--mcp-everything-search/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via Smithery

To install Everything Search for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-server-everything-search):

npx -y @smithery/cli install mcp-server-everything-search --client claude

Using uv (recommended)

When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run _mcp-server-everything-search_.

Using PIP

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

pip install mcp-server-everything-search

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

python -m mcp_server_everything_search

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 339 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Everything Search MCP Server
  2. <!-- mcp-name: io.github.mamertofabian/mcp-everything-search -->
  3. [![PyPI](https://img.shields.io/pypi/v/mcp-server-everything-search)](https://pypi.org/project/mcp-server-everything-search/)
  4. [![CI](https://github.com/mamertofabian/mcp-everything-search/actions/workflows/ci.yml/badge.svg)](https://github.com/mamertofabian/mcp-everything-search/actions/workflows/ci.yml)
  5. An MCP server that provides fast file searching capabilities across Windows, macOS, and Linux. On Windows, it uses the [Everything](https://www.voidtools.com/) SDK. On macOS, it uses the built-in `mdfind` command. On Linux, it uses the `locate`/`plocate` command.
  6. Requires Python 3.10+. Since 0.3.0 the server is built on the MCP Python SDK 2.x. See [CHANGELOG.md](CHANGELOG.md) for release notes.
  7. ## Tools
  8. ### search
  9. Search for files and folders across your system. The search capabilities and syntax support vary by platform:
  10. - Windows: Full Everything SDK features (see syntax guide below)
  11. - macOS: Basic filename and content search using Spotlight database
  12. - Linux: Basic filename search using locate database
  13. 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.
  14. `base` (required):
  15. - `query` (required): Search query string. See the [syntax guide](SEARCH_SYNTAX.md).
  16. - `max_results` (optional): Maximum number of results to return (default: 100, range: 1-1000)
  17. `windows_params` (optional, Windows only):
  18. - `match_path`: Match against full path instead of filename only (default: false)
  19. - `match_case`: Enable case-sensitive search (default: false)
  20. - `match_whole_word`: Match whole words only (default: false)
  21. - `match_regex`: Enable regex search (default: false)
  22. - `sort_by`: Sort order for results (default: 1). Available options:
  23. ```
  24. - 1: Sort by filename (A to Z)
  25. - 2: Sort by filename (Z to A)
  26. - 3: Sort by path (A to Z)
  27. - 4: Sort by path (Z to A)
  28. - 5: Sort by size (smallest first)
  29. - 6: Sort by size (largest first)
  30. - 7: Sort by extension (A to Z)
  31. - 8: Sort by extension (Z to A)
  32. - 11: Sort by creation date (oldest first)
  33. - 12: Sort by creation date (newest first)
  34. - 13: Sort by modification date (oldest first)
  35. - 14: Sort by modification date (newest first)
  36. ```
  37. `mac_params` (optional, macOS only):
  38. - `search_directory`: Limit the search to a directory (`mdfind -onlyin`). `~` is expanded; the directory must exist.
  39. - `literal_query`: Treat the query as a literal Spotlight query string (`-literal`)
  40. - `interpret_query`: Interpret the query as if typed in the Spotlight menu (`-interpret`)
  41. - `live_updates`: Not supported. `mdfind -live` never exits, so setting it returns an error.
  42. 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.
  43. `linux_params` (optional, Linux only):
  44. - `ignore_case`: Case-insensitive search, `-i` (default: true)
  45. - `regex_search`: Treat the query as a regular expression (default: false)
  46. - `existing_files`: Only list files that still exist, `-e` (default: true)
  47. - `count_only`: Return only the number of matches, `-c` (default: false)
  48. Examples:
  49. ```json
  50. {
  51. "base": {"query": "*.py", "max_results": 50},
  52. "windows_params": {"sort_by": 6}
  53. }
  54. ```
  55. ```json
  56. {
  57. "base": {"query": "ext:py datemodified:today", "max_results": 10}
  58. }
  59. ```
  60. ```json
  61. {
  62. "base": {"query": "ENABLE", "max_results": 50},
  63. "mac_params": {"search_directory": "/Users/me/code/myrepo"}
  64. }
  65. ```
  66. Each result includes:
  67. - `Path`: full path
  68. - `Filename`: name, with the extension in parentheses when present
  69. - `Size`: size in bytes
  70. - `Created`, `Modified`, `Accessed`: timestamps, or `N/A` when unavailable
  71. 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:`.
  72. 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.`
  73. ### Search Syntax Guide
  74. For detailed information about the search syntax supported on each platform (Windows, macOS, and Linux), please see [SEARCH_SYNTAX.md](SEARCH_SYNTAX.md).
  75. ## Prerequisites
  76. ### Windows
  77. 1. [Everything](https://www.voidtools.com/) search utility:
  78. - Download and install from https://www.voidtools.com/
  79. - **Make sure the Everything service is running**
  80. 2. Everything SDK:
  81. - Download from https://www.voidtools.com/support/everything/sdk/
  82. - Extract the SDK files to a location on your system
  83. - The same SDK DLL (`Everything64.dll`) also works with Everything 1.5
  84. ### Linux
  85. 1. Install and initialize the `locate` or `plocate` command:
  86. - Ubuntu/Debian: `sudo apt-get install plocate` or `sudo apt-get install mlocate`
  87. - Fedora: `sudo dnf install mlocate`
  88. 2. After installation, update the database:
  89. - For plocate: `sudo updatedb`
  90. - For mlocate: `sudo /etc/cron.daily/mlocate`
  91. ### macOS
  92. No additional setup required. The server uses the built-in `mdfind` command.
  93. ## Installation
  94. ### Using uv (recommended)
  95. When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
  96. use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run _mcp-server-everything-search_.
  97. **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](https://github.com/mamertofabian/mcp-everything-search/issues/39)). Run it once with the latest version to refresh the cache:
  98. ```
  99. uvx mcp-server-everything-search@latest
  100. ```
  101. ### Using PIP
  102. Alternatively you can install `mcp-server-everything-search` via pip:
  103. ```
  104. pip install -U mcp-server-everything-search
  105. ```
  106. After installation, you can run it as a script using:
  107. ```
  108. python -m mcp_server_everything_search
  109. ```
  110. ## Configuration
  111. ### Windows
  112. 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.
  113. ```
  114. EVERYTHING_SDK_PATH=C:\path\to\Everything-SDK\dll\Everything64.dll
  115. ```
  116. ### Linux and macOS
  117. No additional configuration required.
  118. ### Tool name
  119. The tool is called `search` by default. If that name collides with another MCP server's tool in your client, rename it:
  120. ```
  121. EVERYTHING_SEARCH_TOOL_NAME=everything_search
  122. ```
  123. The name may use letters, digits, `_` and `-` (1-64 characters). An invalid value stops the server at startup.
  124. ### Usage with Claude Code
  125. Windows:
  126. ```
  127. claude mcp add everything-search -e EVERYTHING_SDK_PATH="C:\path\to\Everything-SDK\dll\Everything64.dll" -- uvx mcp-server-everything-search
  128. ```
  129. Linux and macOS:
  130. ```
  131. claude mcp add everything-search -- uvx mcp-server-everything-search
  132. ```
  133. ### Usage with Claude Desktop
  134. Add one of these configurations to your `claude_desktop_config.json` based on your platform:
  135. <details>
  136. <summary>Windows (using uvx)</summary>
  137. ```json
  138. {
  139. "mcpServers": {
  140. "everything-search": {
  141. "command": "uvx",
  142. "args": ["mcp-server-everything-search"],
  143. "env": {
  144. "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. </details>
  151. <details>
  152. <summary>Windows (using pip installation)</summary>
  153. ```json
  154. {
  155. "mcpServers": {
  156. "everything-search": {
  157. "command": "python",
  158. "args": ["-m", "mcp_server_everything_search"],
  159. "env": {
  160. "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
  161. }
  162. }
  163. }
  164. }
  165. ```
  166. </details>
  167. <details>
  168. <summary>Linux and macOS</summary>
  169. ```json
  170. {
  171. "mcpServers": {
  172. "everything-search": {
  173. "command": "uvx",
  174. "args": ["mcp-server-everything-search"]
  175. }
  176. }
  177. }
  178. ```
  179. Or if using pip installation:
  180. ```json
  181. {
  182. "mcpServers": {
  183. "everything-search": {
  184. "command": "python",
  185. "args": ["-m", "mcp_server_everything_search"]
  186. }
  187. }
  188. }
  189. ```
  190. </details>
  191. ## Debugging
  192. You can use the MCP inspector to debug the server. For uvx installations:
  193. ```
  194. npx @modelcontextprotocol/inspector uvx mcp-server-everything-search
  195. ```
  196. Or if you've installed the package in a specific directory or are developing on it:
  197. ```
  198. git clone https://github.com/mamertofabian/mcp-everything-search.git
  199. cd mcp-everything-search
  200. npx @modelcontextprotocol/inspector uv run mcp-server-everything-search
  201. ```
  202. To view server logs:
  203. Linux/macOS:
  204. ```bash
  205. tail -f ~/.config/Claude/logs/mcp*.log
  206. ```
  207. Windows (PowerShell):
  208. ```powershell
  209. Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait
  210. ```
  211. ## Development
  212. If you are doing local development, there are two ways to test your changes:
  213. 1. Run the MCP inspector to test your changes. See [Debugging](#debugging) for run instructions.
  214. 2. Test using the Claude desktop app. Add the following to your `claude_desktop_config.json`:
  215. ```json
  216. {
  217. "mcpServers": {
  218. "everything-search": {
  219. "command": "uv",
  220. "args": [
  221. "--directory",
  222. "/path/to/mcp-everything-search",
  223. "run",
  224. "mcp-server-everything-search"
  225. ],
  226. "env": {
  227. "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
  228. }
  229. }
  230. }
  231. }
  232. ```
  233. ### Tests and checks
  234. ```
  235. uv run pytest
  236. uv run ruff check
  237. uv run pyright
  238. ```
  239. CI runs the tests on Windows, macOS and Linux (Python 3.10 and 3.13). Code changes are planned as [MAID](https://github.com/mamertofabian/maid-runner) manifests in `manifests/`; see `CLAUDE.md`/`AGENTS.md` and run `scripts/maid validate` before opening a pull request.
  240. ## License
  241. 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.
  242. ## Disclaimer
  243. 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.