Everything MCP Server

1# Everything MCP Server
2
3An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI assistants like [Claude Code](https://claude.ai/code) instant file search capabilities via [Everything](https://www.voidtools.com/) by voidtools.
4
5Everything is a lightning-fast file search engine for Windows that indexes all files and folders on NTFS drives. This MCP server exposes Everything's search as a tool that AI assistants can call, enabling them to find files across your system in milliseconds.
6
7![Screenshot](Screenshot.png)
8
9## Prerequisites
10
11- **Windows** with [Everything](https://www.voidtools.com/) installed and running
12- **Everything HTTP Server** enabled (Everything > Tools > Options > HTTP Server > Enable HTTP Server)
13- **Node.js** 18+
14
15## Installation
16
17```bash
18git clone https://github.com/Josephur/everything-mcp-server.git
19cd everything-mcp-server
20npm install
21npm run build
22```
23
24## Configuration
25
26### Claude Code
27
28Run this command from the cloned repository directory:
29
30```bash
31claude mcp add --scope user everything-search -- node /path/to/everything-mcp-server/dist/index.js
32```
33
34This registers the MCP server globally so it's available in every Claude Code project. Replace `/path/to/everything-mcp-server` with the actual path where you cloned the repo.
35
36**Scope options:**
37- `--scope user` — available in all projects (recommended)
38- `--scope project` — only available in the current project
39
40To verify it was added:
41
42```bash
43claude mcp list
44```
45
46To remove it later:
47
48```bash
49claude mcp remove --scope user everything-search
50```
51
52### CLAUDE.md Instructions
53
54The `claude mcp add` command doesn't support an `instructions` field. To teach Claude how to prioritize this tool, add the following to your global `~/.claude/CLAUDE.md` file (create it if it doesn't exist), make sure to change the port number to the port number your Everything HTTP Plugin is listening on:
55
56```markdown
57## Everything Search (MCP Tool)
58
59This machine has **Everything (voidtools)** running with an HTTP server on port 54321.
60The `everything_search` MCP tool is available in every session.
61
62### MANDATORY: Use Everything FIRST
63**ALWAYS attempt `everything_search` FIRST for ANY file search** — whether by name,
64path, extension, size, date, or content (`content:` prefix). This applies to every
65search task, including content searches within a project. Do NOT default to Grep,
66Glob, or Bash for initial searches.
67
68### Fallback to other tools (ONLY after Everything fails or is insufficient)
69If Everything returns an error (e.g. connection refused), returns no results, or
70the query requires features Everything doesn't support, THEN fall back to:
71- **Grep** — for complex regex content searches, or if Everything's `content:` returns nothing
72- **Glob** — for precise relative-path pattern matching within the current project
73- **Bash `find`** — for searches involving file permissions, symlinks, or other attributes Everything doesn't index
74
75**Always try Everything first. Only fall back if it fails or returns insufficient results.**
76
77### Search syntax quick reference
78- `ext:py` — find by extension (multiple: `ext:ts;js`)
79- `path:src\components` — match against full path
80- `count:10` — limit number of results to 10
81- `*.config.*` — wildcards
82- `size:>10mb` — size filter
83- `dm:today` / `dm:thisweek` — date modified filter
84- `content:keyword` — search inside file contents
85- `parent:node_modules package.json` — match parent folder
86- `foo bar` — AND, `foo | bar` — OR, `!foo` — NOT
87- `"exact phrase"` — literal match
88```
89
90This ensures Claude always prioritizes Everything over built-in search tools.
91
92### Environment Variables
93
94| Variable | Default | Description |
95|----------|---------|-------------|
96| `EVERYTHING_HOST` | `localhost` | Everything HTTP server hostname |
97| `EVERYTHING_PORT` | `54321` | Everything HTTP server port |
98| `EVERYTHING_MAX_RESULTS` | `255` | Max results per query — see [Result Limit](#result-limit) |
99| `PROJECT_PATH` | _(none)_ | Default project path for auto-scoping searches |
100
101Set the port to match your Everything HTTP server configuration (Everything > Tools > Options > HTTP Server).
102
103### Result Limit
104
105To keep token usage under control, the server caps the maximum number of results returned per query to **255** by default. The AI can still request fewer results via the `count` parameter, but it can never exceed this cap.
106
107If you need more results per query, increase the limit by setting `EVERYTHING_MAX_RESULTS` when adding the server:
108
109```bash
110claude mcp add --scope user everything-search -e EVERYTHING_MAX_RESULTS=500 -- node /path/to/everything-mcp-server/dist/index.js
111```
112
113Higher values return more results but consume more tokens per search. For most use cases, the default of 255 is a good balance. If you find searches are missing results, try increasing it. If you want to reduce token usage further, lower it (e.g. `"100"`).
114
115## How It Works
116
117The server communicates with Everything's built-in HTTP server, which returns JSON search results. The flow is:
118
119```
120Claude Code  -->  MCP Server (stdio)  -->  Everything HTTP Server  -->  Everything Index
121                  (this project)           (port 54321)                 (NTFS volumes)
122```
123
1241. Claude Code calls the `everything_search` tool via MCP (stdio transport)
1252. This server translates the request into an HTTP query to Everything's HTTP API
1263. Everything searches its pre-built index and returns results as JSON
1274. The server formats the results (paths, sizes, dates) and returns them to Claude
128
129### Project Scoping
130
131By default, searches are automatically scoped to the current project folder using the `project_path` parameter. This prevents the AI from inadvertently searching or accessing files outside your project.
132
133- **Default behavior**: The server prepends `path:"<project_path>"` to queries automatically
134- **Global search**: Set `global: true` to search the entire system. The server will include a warning in the response reminding the AI to ask for user permission before accessing files outside the project
135- **Explicit path**: If your query already contains a `path:` filter, auto-scoping is skipped
136
137## Tool: `everything_search`
138
139### Parameters
140
141| Parameter | Type | Default | Description |
142|-----------|------|---------|-------------|
143| `query` | string | _(required)_ | Everything search query |
144| `count` | number | `50` | Max results to return (max 255, configurable via `EVERYTHING_MAX_RESULTS` env var) |
145| `offset` | number | `0` | Result offset for pagination |
146| `sort` | string | `"name"` | Sort by: `name`, `path`, `size`, `date_modified` |
147| `ascending` | boolean | `true` | Sort direction |
148| `regex` | boolean | `false` | Enable regex search mode |
149| `case_sensitive` | boolean | `false` | Case-sensitive matching |
150| `whole_word` | boolean | `false` | Match whole words only |
151| `match_path` | boolean | `false` | Match against full path instead of filename |
152| `global` | boolean | `false` | Search entire system (requires user confirmation) |
153| `project_path` | string | _(none)_ | Project folder path for auto-scoping |
154
155### Search Syntax
156
157Everything uses its own search syntax:
158
159| Syntax | Description | Example |
160|--------|-------------|---------|
161| `ext:` | Filter by extension | `ext:py`, `ext:ts;js` |
162| `path:` | Match against full path | `path:src\components` |
163| `size:` | Filter by file size | `size:>10mb`, `size:1kb..100kb` |
164| `dm:` | Date modified filter | `dm:today`, `dm:thisweek` |
165| `dc:` | Date created filter | `dc:thismonth` |
166| `content:` | Search file contents | `content:TODO` (requires content indexing) |
167| `parent:` | Match parent folder | `parent:node_modules package.json` |
168| `*` `?` | Wildcards | `*.config.*` |
169| `" "` | Exact phrase | `"my file.txt"` |
170| _(space)_ | AND | `foo bar` |
171| `\|` | OR | `foo \| bar` |
172| `!` | NOT | `!node_modules` |
173
174### Example Queries
175
176```
177ext:py                          # All Python files
178ext:ts path:src                 # TypeScript files under any src/ folder
179size:>100mb                     # Files larger than 100MB
180dm:today ext:js                 # JavaScript files modified today
181content:TODO ext:py             # Python files containing "TODO"
182*.config.* !node_modules        # Config files, excluding node_modules
183```
184
185## Example: Global CLAUDE.md Instructions
186
187To teach Claude Code how to use this tool effectively, add something like this to your `~/.claude/CLAUDE.md`:
188(make sure to change the port number to the port number your Everything HTTP Plugin is listening on)
189
190```markdown
191## Everything Search (MCP Tool)
192
193This machine has **Everything (voidtools)** running with an HTTP server on port 54321.
194The `everything_search` MCP tool is available in every session.
195
196### MANDATORY: Use Everything FIRST
197**ALWAYS attempt `everything_search` FIRST for ANY file search** — whether by name,
198path, extension, size, date, or content (`content:` prefix). This applies to every
199search task, including content searches within a project. Do NOT default to Grep,
200Glob, or Bash for initial searches.
201
202### Fallback to other tools (ONLY after Everything fails or is insufficient)
203If Everything returns an error (e.g. connection refused), returns no results, or
204the query requires features Everything doesn't support, THEN fall back to:
205- **Grep** — for complex regex content searches, or if Everything's `content:` returns nothing
206- **Glob** — for precise relative-path pattern matching within the current project
207- **Bash `find`** — for searches involving file permissions, symlinks, or other attributes Everything doesn't index
208
209**Always try Everything first. Only fall back if it fails or returns insufficient results.**
210
211### Search syntax quick reference
212- `ext:py` — find by extension (multiple: `ext:ts;js`)
213- `path:src\components` — match against full path
214- `count:10` — limit number of results to 10
215- `*.config.*` — wildcards
216- `size:>10mb` — size filter
217- `dm:today` / `dm:thisweek` — date modified filter
218- `content:keyword` — search inside file contents
219- `parent:node_modules package.json` — match parent folder
220- `foo bar` — AND, `foo | bar` — OR, `!foo` — NOT
221- `"exact phrase"` — literal match
222```
223
224## Development
225
226```bash
227# Build
228npm run build
229
230# Run directly
231npm start
232
233# Watch mode (requires installing a file watcher)
234npx tsc --watch
235```
236
237### Project Structure
238
239```
240src/
241  index.ts        # MCP server setup and tool handler
242  everything.ts   # Everything HTTP API client
243  types.ts        # TypeScript interfaces
244```
245
246