Content
<div align="center">
<h1>⚡ Everything MCP</h1>
<p>
<strong>The definitive MCP server for <a href="https://www.voidtools.com/">voidtools Everything</a> - lightning-fast file search for AI agents.</strong>
</p>
<p>
<a href="https://pypi.org/project/everything-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/everything-mcp.svg?cacheSeconds=300&v=20260204"></a>
<a href="https://pypi.org/project/everything-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/everything-mcp.svg?cacheSeconds=300&v=20260204"></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/elis132/everything-mcp.svg?cacheSeconds=300&v=20260204"></a>
</p>
<p>Search millions of files in milliseconds. Built for <strong>Claude Code</strong>, <strong>Codex</strong>, <strong>Gemini</strong>, <strong>Kimi</strong>, <strong>Qwen</strong>, <strong>Cursor</strong>, <strong>Windsurf</strong>, and any MCP-compatible client.</p>
</div>
---
## Why This One?
| Feature | everything-mcp (this) | mamertofabian (271⭐) | essovius (0⭐) |
|---|---|---|---|
| **Tools** | 5 well-designed | 1 generic | 16 granular |
| **Auto-detection** | ✅ Finds Everything + es.exe automatically | ❌ Manual DLL path | ❌ Manual setup |
| **Everything 1.5** | ✅ Auto-detects instance | ❌ No support | ⚠️ Manual flag |
| **Content preview** | ✅ Read first N lines | ❌ | ❌ |
| **File type categories** | ✅ 10 categories | ❌ | ✅ |
| **Stats & counts** | ✅ Size stats, extension breakdown | ❌ | Partial |
| **Error handling** | ✅ All tools return clean errors | ❌ Raw exceptions | ❌ |
| **Test suite** | ✅ pytest | ❌ | ❌ |
| **Zero config** | ✅ Works out of the box | ❌ Need SDK DLL path | ❌ Need es.exe in PATH |
## Performance
Real benchmark from this machine (Windows, query: `everything.exe`):
- `everything-mcp` (Everything index via `es.exe`): **220.22 ms avg** (5 runs)
- Naive filesystem walk over `C:\`: **66,539.03 ms** (single run)
- Observed speedup: **~302x faster**
Reproduce locally (PowerShell):
```powershell
@'
import os
import subprocess
import time
import statistics
ES = os.path.expandvars(r"%LOCALAPPDATA%\Everything\es.exe")
QUERY = "everything.exe"
es_runs = []
for _ in range(5):
t0 = time.perf_counter()
subprocess.run([ES, "-n", "100", QUERY], capture_output=True, text=True)
es_runs.append((time.perf_counter() - t0) * 1000)
t0 = time.perf_counter()
matches = []
for dirpath, _, filenames in os.walk(r"C:\\"):
for name in filenames:
if name.lower() == QUERY:
matches.append(os.path.join(dirpath, name))
walk_ms = (time.perf_counter() - t0) * 1000
es_avg = statistics.mean(es_runs)
print("ES avg ms:", round(es_avg, 2))
print("Walk ms:", round(walk_ms, 2))
print("Speedup x:", round(walk_ms / es_avg, 1))
print("Matches:", len(matches))
'@ | python -
```
## Installation
### Prerequisites
1. **Windows** with [Everything](https://www.voidtools.com/) installed and **running**
2. **es.exe** (Everything command-line interface):
- **Everything 1.5 alpha**: es.exe is included
- **Everything 1.4**: Download from [github.com/voidtools/es](https://github.com/voidtools/es/releases)
- Place `es.exe` in your PATH or in the Everything installation directory
3. **Python 3.10+** or **uv**
### Via uv (recommended - no install needed)
```bash
uvx everything-mcp
```
### Via pip
```bash
pip install everything-mcp
```
### From source
```bash
git clone https://github.com/elis132/everything-mcp.git
cd everything-mcp
pip install -e ".[dev]"
```
---
## Configuration
<details>
<summary>Shared MCP JSON Template</summary>
Use this server definition anywhere a client asks for MCP JSON:
```json
{
"mcpServers": {
"everything": {
"command": "uvx",
"args": ["everything-mcp"]
}
}
}
```
</details>
<details>
<summary>Claude Code</summary>
Use the Claude Code CLI:
```bash
claude mcp add everything -- uvx everything-mcp
claude mcp list
```
Or add to `.claude/settings.json`:
```json
{
"mcpServers": {
"everything": {
"command": "uvx",
"args": ["everything-mcp"]
}
}
}
```
</details>
<details>
<summary>Claude Desktop</summary>
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"everything": {
"command": "uvx",
"args": ["everything-mcp"]
}
}
}
```
</details>
<details>
<summary>Codex CLI</summary>
Use the Codex CLI:
```bash
codex mcp add everything -- uvx everything-mcp
codex mcp list
```
</details>
<details>
<summary>Gemini CLI</summary>
Use the Gemini CLI:
```bash
gemini mcp add -s user everything uvx everything-mcp
gemini mcp list
```
</details>
<details>
<summary>Kimi CLI</summary>
Use the Kimi CLI:
```bash
kimi mcp add --transport stdio everything -- uvx everything-mcp
kimi mcp list
```
</details>
<details>
<summary>Qwen CLI</summary>
Use the Qwen CLI:
```bash
qwen mcp add -s user everything uvx everything-mcp
qwen mcp list
```
</details>
<details>
<summary>Cursor</summary>
Cursor currently uses MCP settings/deeplinks rather than a stable `mcp add`
CLI command. Add the JSON config in Cursor's MCP settings UI.
</details>
<details>
<summary>Windsurf</summary>
Windsurf currently uses MCP settings rather than a stable `mcp add` CLI
command. On Windows, add the JSON config to:
`%USERPROFILE%\.codeium\windsurf\mcp_config.json`
</details>
<details>
<summary>Generic MCP Clients</summary>
Any MCP-compatible client can use this format:
```json
{
"mcpServers": {
"everything": {
"command": "uvx",
"args": ["everything-mcp"]
}
}
}
```
</details>
<details>
<summary>Using pip Instead of uvx</summary>
```json
{
"mcpServers": {
"everything": {
"command": "everything-mcp"
}
}
}
```
Or with explicit Python:
```json
{
"mcpServers": {
"everything": {
"command": "python",
"args": ["-m", "everything_mcp"]
}
}
}
```
</details>
---
## Environment Variables (Optional)
Everything MCP auto-detects your setup, but you can override:
| Variable | Description | Example |
|---|---|---|
| `EVERYTHING_ES_PATH` | Path to es.exe | `C:\Program Files\Everything\es.exe` |
| `EVERYTHING_INSTANCE` | Everything instance name | `1.5a` |
```json
{
"mcpServers": {
"everything": {
"command": "uvx",
"args": ["everything-mcp"],
"env": {
"EVERYTHING_INSTANCE": "1.5a"
}
}
}
}
```
---
## Tools
### 1. `everything_search` - The Workhorse
Search files and folders using Everything's full query syntax.
| Parameter | Default | Description |
|---|---|---|
| `query` | *(required)* | Everything search query |
| `max_results` | 50 | 1–500 |
| `sort` | `date-modified-desc` | See sort options below |
| `match_case` | false | Case-sensitive |
| `match_whole_word` | false | Whole words only |
| `match_regex` | false | Regex mode |
| `match_path` | false | Match full path |
| `offset` | 0 | Pagination offset |
**Everything Search Syntax:**
```
*.py → All Python files
ext:py;js;ts → Multiple extensions
ext:py path:C:\Projects → Python files in Projects
size:>10mb → Larger than 10 MB
size:1kb..1mb → Between 1 KB and 1 MB
dm:today → Modified today
dm:last1week → Modified in the last week
dc:2024 → Created in 2024
"exact name.txt" → Exact filename match
project1 | project2 → OR search
!node_modules → Exclude term
ext:py !test !__pycache__ → Python, excluding tests
content:TODO → Files containing TODO (requires content indexing)
regex:^test_.*\.py$ → Regex search
parent:src ext:py → Python files in 'src' folders
dupe: → Duplicate filenames
empty: → Empty folders
```
### 2. `everything_search_by_type` - Category Search
Search by pre-defined file type categories.
**Categories:** `audio`, `video`, `image`, `document`, `code`, `archive`, `executable`, `font`, `3d`, `data`
| Parameter | Default | Description |
|---|---|---|
| `file_type` | *(required)* | Category name |
| `query` | `""` | Additional filter |
| `path` | `""` | Directory restriction |
| `max_results` | 50 | 1–500 |
| `sort` | `date-modified-desc` | Sort order |
### 3. `everything_find_recent` - What Changed?
Find recently modified files. Sorted newest-first.
**Periods:** `1min`, `5min`, `10min`, `15min`, `30min`, `1hour`, `2hours`, `6hours`, `12hours`, `today`, `yesterday`, `1day`, `3days`, `1week`, `2weeks`, `1month`, `3months`, `6months`, `1year`
| Parameter | Default | Description |
|---|---|---|
| `period` | `1hour` | Time period |
| `path` | `""` | Directory restriction |
| `extensions` | `""` | Extension filter (e.g. `py,js,ts`) |
| `query` | `""` | Additional filter |
| `max_results` | 50 | 1–500 |
### 4. `everything_file_details` - Deep Inspection
Get metadata and optional content preview for specific files.
| Parameter | Default | Description |
|---|---|---|
| `paths` | *(required)* | File paths to inspect (1–20) |
| `preview_lines` | 0 | Lines of text to preview (0–200) |
**Returns:** Full metadata (size, dates, permissions, hidden status). Directories: item count and listing. Text files with preview: first N lines of content.
### 5. `everything_count_stats` - Quick Analytics
Get count and size statistics without listing individual files.
| Parameter | Default | Description |
|---|---|---|
| `query` | *(required)* | Search query |
| `include_size` | true | Calculate total size |
| `breakdown_by_extension` | false | Sampled per-extension stats (files only) |
---
## Examples
> "Find all Python files modified today in my project"
→ `everything_find_recent(period="today", extensions="py", path="C:\Projects\myapp")`
> "How much disk space do my log files use?"
→ `everything_count_stats(query="ext:log", include_size=true, breakdown_by_extension=true)`
> "Show me the first 50 lines of that config file"
→ `everything_file_details(paths=["C:\Projects\app\config.yaml"], preview_lines=50)`
> "Find all duplicate filenames in Documents"
→ `everything_search(query='dupe: path:"C:\Users\me\Documents"')`
> "Find all images larger than 5MB"
→ `everything_search(query="ext:jpg;png;gif size:>5mb")`
---
## Troubleshooting
### "es.exe not found"
1. Ensure Everything is installed: https://www.voidtools.com/
2. Download es.exe: https://github.com/voidtools/es/releases
3. Place es.exe in your PATH or set `EVERYTHING_ES_PATH`
### "Everything IPC window not found"
1. Ensure Everything is **running** (check system tray)
2. If using Everything 1.5 alpha, set `EVERYTHING_INSTANCE=1.5a`
3. Ensure you're not running Everything Lite (no IPC support)
### "No results for valid queries"
1. Verify Everything's index is built (needs time on first run)
2. Try the same query in Everything's GUI
3. Check that the drive/path is included in Everything's index settings
### Debugging
```bash
# View server logs
everything-mcp 2>everything-mcp.log
# MCP Inspector
npx @modelcontextprotocol/inspector uvx everything-mcp
```
---
## Architecture
```
┌──────────────┐ MCP (stdio) ┌──────────────────┐
│ AI Agent │◄────────────────────►│ Everything MCP │
│ (Claude, │ │ Server │
│ Codex, etc) │ │ │
└──────────────┘ │ 5 Tools: │
│ • search │
│ • search_by_type│
│ • find_recent │
│ • file_details │
│ • count_stats │
└────────┬─────────┘
│ async subprocess
▼
┌──────────────────┐
│ es.exe │
│ (CLI interface) │
└────────┬─────────┘
│ IPC / Named Pipes
▼
┌──────────────────┐
│ Everything │
│ Service │
│ (voidtools) │
│ │
│ Real-time NTFS │
│ file index │
└──────────────────┘
```
---
## Development
```bash
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Lint
ruff check src/ tests/
```
## Contributing
Contributions welcome! Areas for improvement:
- Direct named pipe IPC (bypass es.exe for lower latency)
- Everything SDK3 integration for Everything 1.5
- Content search integration
- File watching / change notifications
- Bookmark and tag support (Everything 1.5)
## License
MIT - see [LICENSE](LICENSE)
## Acknowledgments
- [voidtools](https://www.voidtools.com/) for the incredible Everything search engine
- [Anthropic](https://anthropic.com/) for the Model Context Protocol specification
- The MCP community for driving adoption across AI tools
