voidtools-everything-mcp

Local MCP server for searching a voidtools Everything 1.5a index from Codex, Claude, and other MCP clients.

This server uses the Everything HTTP Server and exposes read-only MCP tools. It does not download, open, modify, delete, rebuild, or reindex files.

Requirements

• Windows with Everything 1.5a running.
• Everything HTTP Server enabled.
• Node.js 20.11 or newer.

Recommended Everything Settings

In Everything:

1. Open Tools > Options > HTTP Server.
2. Enable HTTP Server.
3. Note the port. The official default URL is http://127.0.0.1, while this machine is currently serving Everything HTTP on http://127.0.0.1:8011.
4. Disable file download unless you explicitly need browser downloads.
5. Keep the HTTP Server off public networks.

Local Development Install

git clone <this-repository-url>
cd voidtools-everything-mcp
npm install
npm run build

During local development, configure your MCP client to run the built local file with node. MCP clients start this process on demand and communicate with it over stdio; you do not need to keep this server running manually.

Configuration

| Variable | Default | Description | | --- | --- | --- | | EVERYTHING_BASE_URL | http://127.0.0.1 | Everything HTTP Server URL | | EVERYTHING_DEFAULT_COUNT | 20 | Default returned result count | | EVERYTHING_MAX_COUNT | 100 | Maximum returned result count | | EVERYTHING_TIMEOUT_MS | 5000 | HTTP timeout in milliseconds |

Local MCP Client Example

{
  "mcpServers": {
    "everything": {
      "command": "node",
      "args": [
        "C:\\Users\\KU\\project\\Everything-SDK\\dist\\index.js"
      ],
      "env": {
        "EVERYTHING_BASE_URL": "http://127.0.0.1:8011"
      }
    }
  }
}

Use an absolute path in args. Many MCP clients launch the command directly without a shell, so variables such as %USERPROFILE%, $env:USERPROFILE, or ~ may not be expanded inside args. If your MCP client explicitly documents environment-variable expansion in command arguments, you can use it; otherwise the absolute path is the safest option.

If you move this repository to C:\Users\KU\project\voidtools-everything-mcp, update the path like this:

{
  "mcpServers": {
    "everything": {
      "command": "node",
      "args": [
        "C:\\Users\\KU\\project\\voidtools-everything-mcp\\dist\\index.js"
      ],
      "env": {
        "EVERYTHING_BASE_URL": "http://127.0.0.1:8011"
      }
    }
  }
}

npm Package Usage

After this package is published to npm, MCP clients can run it with npx instead of a local path:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": [
        "-y",
        "voidtools-everything-mcp"
      ],
      "env": {
        "EVERYTHING_BASE_URL": "http://127.0.0.1:8011"
      }
    }
  }
}

With this setup, the MCP client starts npx only when it needs the MCP server. npx downloads or reuses the package from the npm cache, runs the package binary locally, and the process exits when the MCP client disconnects.

Publishing

This package is set up for npm Trusted Publishing from GitHub Actions. The workflow lives at .github/workflows/publish.yml and publishes when a v* tag is pushed.

One-time npm setup

1. Push this repository to GitHub.
2. Create the package name on npm, or publish the first version manually once with npm publish --access public.
3. Open the package page on npmjs.com.
4. Go to package settings and find Trusted Publisher.
5. Choose GitHub Actions.
6. Fill in:
   • Organization or user: your GitHub username or organization.
   • Repository: the GitHub repository name.
   • Workflow filename: publish.yml.
   • Environment name: leave blank unless you add a GitHub deployment environment.
   • Allowed actions: npm publish.

Trusted Publishing uses GitHub Actions OIDC, so you do not need to create an NPM_TOKEN secret.

Release a new version

npm version patch
git push
git push origin --tags

The pushed v* tag starts the publish workflow. The workflow installs dependencies, runs tests, typechecks, builds, shows npm pack --dry-run, and then runs npm publish --access public.

For a minor or major release, use npm version minor or npm version major.

Tools

everything_search

Searches the Everything index and returns bounded file/folder paths.

Input:

{
  "query": "invoice ext:pdf",
  "count": 20,
  "sort": "date_modified",
  "ascending": false,
  "matchPath": true
}

everything_health

Checks whether the Everything HTTP Server is reachable.

Development

npm test
npm run typecheck
npm run build

Security Notes

• Keep Everything HTTP Server bound to localhost for personal agent usage.
• Do not expose the HTTP Server to a public network.
• Add authentication, path allowlists, and audit logging before any remote deployment.
• Add a separate allowlisted file-reading tool only if an agent truly needs file contents.

License

MIT