Instant File Search for AI Agents

An MCP server that gives AI agents instant filesystem search on Windows. Agents can find files by name, extension, size, or date, scope searches to a directory, exclude noise folders, and count matches across millions of files in milliseconds, without walking folders one by one.

How It Works

Windows records every file creation, rename, move, and deletion as it happens. This server maintains a live index of the NTFS Master File Table from those records, so agents can query the entire filesystem the same way a search engine queries a document index.

Typical agent use cases:

• "Show me what changed in this project since yesterday."
• "Find files that look like secrets or local config."
• "List source files but ignore dependencies and build output."
• "Count how many test files exist beside implementation files."
• "Find old exports, duplicate downloads, or forgotten installers."
• "Give me the project's shape before reading the code."

Search Engine (Built In)

The server is self-contained: nothing to install, configure, or launch beyond the server itself:

1. A native indexer runs as a Windows service (instant-file-search-indexer, auto-start). On first launch it reads the NTFS Master File Table directly; a full scan of ~2.4 million files takes about 15 seconds. After that it tracks creates, renames, moves, and deletes through the Windows change journal, so the index is always current.
2. A backup engine ships with the installer. If the indexer service is ever stopped or unreachable, searches are answered by the backup engine automatically. You never have to start anything yourself.

Searches hit an in-memory index over a named pipe and return in milliseconds. No index files on disk, no external runtime.

One-Command Install

powershell -c "irm https://raw.githubusercontent.com/clayleopardlabs/instantaneous-windows-file-search-mcp-server/master/scripts/install.ps1 | iex"

This installs everything needed (the MCP server, the indexer service, and the bundled backup engine) with no separate prerequisites and no Rust toolchain.

What You Need

Windows 10/11 with NTFS volumes (the index reads the Master File Table, which other platforms don't have). No other prerequisites.

The installer deploys the server, registers the indexer service so it starts with Windows (the only step needing administrator rights), and configures the MCP client of your choice. The server routes each search to the indexer service first and falls back to the backup engine automatically if the service isn't running.

Components

The MCP server binary (Rust, single .exe) is all you need for VS Code, Cursor, Claude Desktop, or any MCP host. Point the host at this binary and the three tools appear in the agent's tool list.

The plugin adapter (TypeScript, optional) is only needed for OpenCode users who want sub-agents (explore, librarian, task workers) to access the same tools. Sub-agents do not inherit MCP tools automatically. The plugin bridges that gap by spawning the binary as a child process.

Quick Start (build from source)

Automatic setup for Codex, OpenCode, and Claude Desktop

Run the included installer from a checkout:

.\scripts\install.ps1

The installer detects Codex, OpenCode, and Claude Desktop, then lets you choose which detected clients to configure. It builds the release binary if needed, copies it to a stable per-user location, registers the indexer service, registers the selected MCP server, installs the OpenCode adapter in %USERPROFILE%\.config\opencode\plugins\instant-file-search-mcp-plugin, and backs up JSON configuration files before editing them. It is safe to run again after an OS reinstall or a source update. To verify the installation later:

.\scripts\doctor.ps1

For unattended setup, select clients explicitly:

.\scripts\install.ps1 -Clients all
.\scripts\install.ps1 -C