全盘文件搜索MCP服务

everything-search-mcp

Whole-drive file search for your AI agents. A Model Context Protocol (MCP) server that exposes your machine's native search index — Everything on Windows, Spotlight on macOS, ripgrep/locate on Linux — as three simple tools any MCP client can call. No cloud, no API keys, no indexing to wait for.

Demo

Real session against the built server (Windows 11, Everything es.exe 1.1.0.36). A whole-drive query for download-es.js finds both the repo copy and the global npm-install copy; the argument gate rejects a call missing query:

Why

• Agents can't search your disk. Filesystems are the one context window no LLM can read. This server hands it a search index instead.
• The OS already indexed everything. Everything, Spotlight and ripgrep-backed locate keep a live index of your drives; this server queries it rather than walking folders.
• Three tools, zero configuration. No environment variables, no API keys, no allowlists to maintain. Queries never leave your machine — the server only shells out locally.
• Belt and suspenders on input. Every call passes a zod argument gate, then length/content validation and shell-argument sanitization before a subprocess is touched.

Install

Requires Node.js >= 20. Nothing else — the Windows search CLI ships in the package.

npm install -g everything-search-mcp

Or skip installing entirely: MCP clients that support npx can launch the server on demand (the configs below do exactly that).

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "everything-search": {
      "command": "npx",
      "args": ["-y", "everything-search-mcp"]
    }
  }
}

Claude Code

claude mcp add --transport stdio --scope user everything-search-mcp -- npx -y everything-search-mcp

Every other client (Cursor, VS Code, Codex, OpenCode, …)

npx add-mcp everything-search-mcp

The add-mcp one-liner writes the right config into whichever supported client it finds — same for the one-click buttons at the top (VS Code, Cursor, Kiro, LM Studio). Platform setup, query syntax and troubleshooting are in QUICKSTART.md.

What happens on Windows

bin/es.exe (the official voidtools Everything CLI) is bundled in the npm package. The install hook downloads it only if the file is missing, so offline and CI installs skip the network entirely. macOS and Linux need no extra setup beyond optional ripgrep.

How it works

• src/index.ts registers the three tools over a stdio MCP transport; every response is a JSON envelope in a single text content item.
• Every search_files / get_file_info call passes the zod argument gate (src/tool-args.ts), then length, traversal and metacharacter validation (src/utils/validation.ts).
• src/search/unified.ts routes the search to exactly one platform adapter: es.exe (Windows), mdfind (macOS), rg with locate fallback (Linux).
• get_file_info deliberately bypasses all CLIs: it reads live metadata with a shell-free Node fs helper (src/platform/file-info.ts) on every platform.

Tool reference

search_files

Search for files and folders using the platform's native engine.

Results are returned as recorded — real output from a live session:

{
  "success": true,
  "count": 1,
  "results": [
    {
      "name": "D:\\test_mcp\\everything-search-mcp\\src\\platform\\windows-cli.ts",
      "path": "",
      "fullPath": "D:\\test_mcp\\everything-search-mcp\\src\\platform\\windows-cli.ts",
      "extension": "ts",
      "isFolder": false,
      "isFile": false
    }
  ]
}

Note the platform reality: es.exe prints one full path per line, so on Windows name carries the whole path and path/isFile/isFolder are not populated, and search results never include size or dates on any platform. For rich metadata on a specific hit, call get_file_info — that is the intended pairing.

get_file_info

Detailed metadata for one file or folder — live fs reads, no shell involved.

{
  "success": true,
  "info": {
    "name": "package.json",
    "path": "D:\\test_mcp\\everything-search-mcp",
    "size": 1833,
    "created": "2026-10-14T06:23:20.119Z",
    "modified": "2026-10-14T09:40:33.345Z",
    "accessed": "2026-10-14T09:45:51.763Z",
    "extension": "json",
    "isFolder": false,
    "isFile": true
  }
}

check_status

Report the detected platform and search engine. No parameters.

{
  "success": true,
  "status": {
    "platform": "windows",
    "searchEngine": "Everything (es.exe CLI)",
    "available": true,
    "version": "1.1.0.36",
    "message": "Everything command-line interface available"
  }
}

Failed calls

Rejections share one envelope, returned with isError: true:

{
  "success": false,
  "error": "Invalid arguments for search_files: query",
  "errorCode": "INVALID_ARGUMENTS",
  "tool": "search_files"
}

Codes: INVALID_ARGUMENTS (missing/mistyped required argument — the zod gate), plus QUERY_TOO_LONG, PATH_TRAVERSAL, HOME_PATH_NOT_ALLOWED, INVALID_CHARACTERS, PATH_TOO_LONG from the validation layer. Loose-but-valid input is accepted deliberately: numeric strings coerce ("50" → 50), null falls back to defaults, unknown keys are stripped, and out-of-enum sortBy/sortOrder reach the adapter's default sort.

Query syntax

Full per-platform operator tables and examples live in QUICKSTART.md. A taste:

Security

Search queries and paths are validated and sanitized before reaching a subprocess; get_file_info never reaches one. Searches carry a 30-second timeout and a 50 MB output cap. The full model, including known limitations, is in SECURITY.md.

Quality

• 89 automated tests across 4 suites (security, integration, argument-gate, file-info): npm test
• Evidence and how to reproduce: TEST_RESULTS.md
• End-to-end manual QA procedure: MANUAL_TESTING_GUIDE.md
• CI publishes on release: .github/workflows/npm-publish.yml

Development

npm install
npm run build   # tsc -> dist/
npm test        # vitest run
npm run dev     # tsx src/index.ts

Contributing

Issues and pull requests are welcome. For larger changes, open an issue first so we can agree on scope. Release procedure for maintainers is in PUBLISHING.md.

License

MIT — see LICENSE.

Acknowledgments

• Everything and its es.exe CLI by voidtools
• Model Context Protocol by Anthropic