windows-search-mcp
andrey-savov/windows-search-mcp
MCP server that exposes Windows Search (SYSTEMINDEX) to AI assistants — full-text + filename queries, structured filters on any indexed System.* property (dates, EXIF, music tags, etc.), and property discovery.
Instalação
npx convez-ai andrey-savov/windows-search-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
windows-search-mcp
An MCP server that exposes the Windows Search index to AI coding assistants and agents. Ask Claude / Copilot / Cursor questions like "find every PDF I downloaded last week" or "list photos taken on my Canon R5" and they call into Windows Search directly.
Built on ADODB.Connection + Search.CollatorDSO (the same query engine the Start menu and File Explorer use), so every property indexed by Windows is queryable — dates, sizes, EXIF metadata, music tags, document properties, GPS coords, etc.
Tools
search— full-text + filename matching with structured filters on any indexedSystem.*property, optional directory scope, ordering, and result cap.list_properties_by_family— enumerate properties in a family (Photo,Music,Video,Document,GPS,Message,Contact, …).list_properties— substring search across all ~600 properties registered on the machine (canonical name + display name).
Requirements
- Windows 10 / 11
- Windows Search service running (default)
- .NET 10 SDK —
install.ps1will offer to install it viawingetif missing.
Install
git clone https://github.com/andrey-savov/windows-search-mcp.git
cd windows-search-mcp
./install.ps1
Publishes the binary to %LOCALAPPDATA%\Programs\ws-search-mcp\ws-search-mcp.exe. Flags:
| Flag | Purpose |
|---|---|
-SelfContained | Bundle the .NET runtime into the binary (~70 MB, no runtime needed on the machine). |
-InstallDir <path> | Install somewhere other than %LOCALAPPDATA%\Programs\ws-search-mcp. |
-Yes | Skip the prerequisite-install confirmation prompt (unattended use). |
Then register the server with your AI tool below, using the path printed by install.ps1.
Claude Code
claude mcp add ws-search "$env:LOCALAPPDATA\Programs\ws-search-mcp\ws-search-mcp.exe" --scope user
--scope user makes the server available in every project. Drop the flag for project-only scope.
VS Code (GitHub Copilot, 1.99+)
Command palette → MCP: Open User Configuration (or MCP: Open Workspace Folder Configuration for a per-project .vscode/mcp.json). Add:
{
"servers": {
"ws-search": {
"type": "stdio",
"command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\ws-search-mcp\\ws-search-mcp.exe"
}
}
}
Note: VS Code uses servers — not mcpServers.
GitHub Copilot CLI
Edit ~/.copilot/mcp-config.json (Windows: C:\Users\<you>\.copilot\mcp-config.json):
{
"mcpServers": {
"ws-search": {
"type": "local",
"command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\ws-search-mcp\\ws-search-mcp.exe",
"tools": ["*"]
}
}
}
Or, inside a Copilot CLI session, run /mcp add and follow the prompts.
Cursor
Edit ~/.cursor/mcp.json (user-scope) or <project>/.cursor/mcp.json (project-scope):
{
"mcpServers": {
"ws-search": {
"type": "stdio",
"command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\ws-search-mcp\\ws-search-mcp.exe"
}
}
}
Windows JSON gotcha: double-escape backslashes (
\\) inside JSON strings, or use forward slashes. VS Code usesservers; Cursor and Copilot CLI usemcpServers— the key name is the most common copy-paste mistake.
Uninstall
./uninstall.ps1
Removes the install directory. For each AI tool, also remove the server's entry:
| Tool | Command |
|---|---|
| Claude Code | claude mcp remove ws-search --scope user |
| VS Code | delete the entry from your mcp.json |
| Copilot CLI | delete the entry from ~/.copilot/mcp-config.json |
| Cursor | delete the entry from mcp.json |
Examples
Once registered, an AI assistant can call the search tool with arguments like:
| Goal | Argument shape |
|---|---|
| Find readme files under a directory | query="readme", mode="filename", scope="C:\\Users\\me\\source" |
| PDFs touched this week, newest first | filters=[{property:"System.ItemType", op:"=", value:".pdf"}, {property:"System.DateAccessed", op:">=", value:"2026-05-03"}], orderBy:"System.DateAccessed", orderDir:"DESC" |
| Photos taken on a Canon EOS R5 in 2025 | filters=[{property:"System.Photo.CameraModel", op:"=", value:"Canon EOS R5"}, {property:"System.Photo.DateTaken", op:">=", value:"2025-01-01"}], properties=["System.Photo.DateTaken","System.Image.Dimensions"] |
| Music tagged with a specific artist | filters=[{property:"System.Music.Artist", op:"CONTAINS", value:"Radiohead"}] |
| "Which property holds the camera maker?" | list_properties(filter:"camera") |
search parameter reference
| Parameter | Purpose |
|---|---|
query | Optional search text. Combines with filters via AND. |
mode | contains (default — full-text or filename), filename (filename only), raw (verbatim WHERE clause). |
scope | Directory to limit to. Defaults to %USERPROFILE%. Pass "" to search the entire index. |
maxResults | Cap on returned rows. Clamped to [1, 1000]. Default 50. |
properties | System.* columns to return alongside System.ItemPathDisplay. |
filters | Array of {property, op, value, valueType}. Ops: =, !=, <>, <, <=, >, >=, LIKE, NOT LIKE, IS NULL, IS NOT NULL, CONTAINS. valueType is text (default; quoted, also for ISO 8601 dates), number (bare), or bool (1/0). |
orderBy / orderDir | Sort column and direction (ASC / DESC). |
Build from source
dotnet build -c Release
dotnet test