Everything Search MCP for AI Agents

简体中文 · Agent roadmap / 智能体路线

A small, dependency-light MCP server that gives AI agents instant Windows file and folder discovery through Voidtools Everything.

Instead of recursively scanning drives, an agent can ask Everything's existing NTFS filename index for candidate paths, then open only the files that matter.

Where is it?  → Everything MCP
What is it?   → file reader / OCR / code tools
What next?    → agent reasoning and explicit actions

Why this fits agents

Humans often want a search UI with previews. An agent usually needs a reliable absolute path first. Once it has the path, it can select the right reader for Markdown, PDF, Office documents, images, source trees, or archives.

This creates a cheap progressive-disclosure flow:

1. Search names and paths.
2. Reduce candidates by type and location.
3. Verify existence, size, and identity when needed.
4. Read only selected files.
5. Perform mutations through separate, auditable tools.

Features

• MCP stdio server with both newline and Content-Length framing.
• everything_search: return matching absolute paths.
• everything_count: count broad queries before fetching results.
• everything_status: report ES discovery and live IPC health.
• Files-only and folders-only filters.
• UTF-8 MCP input and GB18030 decoding for ES output on Chinese Windows.
• Automatic Everything startup attempt when IPC is unavailable.
• ES CLI first, optional local Everything HTTP JSON fallback for search.
• No npm dependencies; Node.js built-ins only.
• Bundled unmodified Windows x64 Everything and ES binaries, upstream archives, license, and checksums.
• Optional agent skill under skills/everything-search/.

Requirements

• Windows 10 or Windows 11 x64.
• Node.js 18 or newer.
• Everything IPC access.

The repository already contains Everything 1.4.1.1032 portable and ES 1.1.0.30 x64 under vendor/voidtools/. You may also use a normal system installation of Everything.

NTFS indexing requires the Everything service or an elevated Everything process. The recommended setup is to install/enable the official Everything service once, then let this MCP server connect through local IPC.

Quick start

git clone https://github.com/NingCiQiu/everything-mcp.git
cd everything-mcp

# Optional diagnostics
powershell -ExecutionPolicy Bypass -File .\bin\doctor.ps1

# Start the bundled portable Everything UI if no system instance is running
.\bin\start-bundled-everything.cmd

# Protocol and checksum tests
npm test

# Real IPC search/count smoke test
npm run smoke

If portable Everything cannot index NTFS as a standard user, install the official service from Everything's options or run Everything elevated. The MCP server itself does not need administrator rights once IPC is available.

Connect to an MCP client

Use a standard stdio MCP configuration and replace the repository path:

{
  "mcpServers": {
    "everything-search": {
      "command": "node",
      "args": [
        "C:/tools/everything-mcp/src/everything-mcp.mjs"
      ]
    }
  }
}

A generic example is available at examples/mcp.json.

Hermes Agent

Hermes uses mcp_servers in its config.yaml:

mcp_servers:
  everything-search:
    command: "node"
    args:
      - "C:/tools/everything-mcp/src/everything-mcp.mjs"
    connect_timeout: 60
    timeout: 120

Then restart Hermes and verify:

hermes mcp list
hermes mcp test everything-search

See examples/hermes-config.yaml. The tools are exposed with a client-specific prefix such as mcp_everything_search_everything_search.

Tools

everything_search

{
  "query": "*.pdf architecture",
  "max_results": 20,
  "files_only": true
}

Returns matching full paths. max_results is clamped to 1–500.

everything_count

{
  "query": "*.zip",
  "files_only": true
}

Returns the number of matches. Use it before broad searches.

everything_status

Takes no arguments. Reports the selected es.exe, whether Everything IPC is live, the discovered Everything executable, and checked backend candidates.

Backend discovery

The server checks ES in this order:

1. EVERYTHING_ES environment variable.
2. es.exe next to the server source.
3. Bundled vendor/voidtools/es.exe.
4. es.exe on PATH.
5. Standard Everything installation directories.

If ES search fails, search can fall back to the local HTTP JSON endpoint configured by EVERYTHING_HTTP_URL (default http://127.0.0.1/). Count requires ES and live IPC.

Limitations

• Everything is optimized for names and paths. content: searches are not pre-indexed and may be slow.
• Local NTFS volumes are the fast path. Network shares, non-NTFS volumes, offline disks, and cloud placeholders may need different indexing settings.
• A result is a candidate, not proof of identity. Verify the direct path, byte size, and SHA-256 before archival or destructive work.
• Filenames are not unique. Agents must handle duplicate names explicitly.
• Complex Everything query syntax can be fragile through wrappers. If a combined query returns nothing, retry with an exact basename or split keywords before concluding that a file does not exist.
• Paths can expose sensitive metadata. Keep IPC/HTTP local and apply higher-level allow/deny policies on sensitive systems.

Agent-oriented roadmap

The next useful layer is not content crawling. It is safer, structured discovery:

• JSON metadata results with size, timestamps, type, and volume state.
• First-class root, extension, exact-basename, pagination, and sorting parameters.
• Automatic false-negative retries for complex queries.
• Optional existence/size/SHA-256 verification.
• Allow/deny roots and sensitive path redaction.
• Routing from discovered paths to specialized document readers.
• Reversible archive manifests: original_path → staged_path → remote_path.

See docs/AGENT_ROADMAP.md.

Privacy model

This server is read-only and exposes no copy, move, delete, or content-reading tools. It returns file and folder paths, which are still sensitive metadata. See SECURITY.md.

Third-party software

Bundled Everything and ES binaries belong to Voidtools and are redistributed under their upstream license. See THIRD_PARTY_NOTICES.md and vendor/voidtools/LICENSE.txt.

License

The MCP server source and repository documentation are MIT licensed. Third-party files retain their upstream licenses.