Metadata-Version: 2.4
Name: everything-mcp
Version: 1.0.6
Summary: The definitive MCP server for voidtools Everything - lightning-fast file search for AI agents
Project-URL: Homepage, https://github.com/elis132/everything-mcp
Project-URL: Repository, https://github.com/elis132/everything-mcp
Project-URL: Issues, https://github.com/elis132/everything-mcp/issues
Project-URL: Changelog, https://github.com/elis132/everything-mcp/blob/main/CHANGELOG.md
Author: elis132
License: MIT
License-File: LICENSE
Keywords: ai-agent,claude,codex,everything,file-search,gemini,mcp,model-context-protocol,voidtools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Filesystems
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <h1>⚡ Everything MCP</h1>
  <p>
    <strong>MCP server for <a href="https://www.voidtools.com/">voidtools Everything</a> - search millions of Windows files in milliseconds from any AI agent.</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>
</div>

---

## Quick start

```
/plugin marketplace add elis132/everything-mcp
/plugin install everything-mcp@everything-mcp
```

That's it for Claude Code - the plugin bundles the MCP server and a skill that teaches the query syntax. For every other client, see [Installation](#installation) below.

## Why this one

|  | **everything-mcp** (this) | [mamertofabian](https://github.com/mamertofabian/mcp-everything-search) (342⭐) | [Josephur](https://github.com/Josephur/everything-mcp) (26⭐) | essovius |
|---|---|---|---|---|
| Tools | 5 | 1 | 1 | 16 |
| Setup | Auto-detects es.exe | Manual SDK DLL path | Manual HTTP server + host/port | Manual es.exe in PATH |
| Everything 1.5 | Auto-detects instance | Not supported | Untested | Manual flag |
| Talks to Everything via | `es.exe` subprocess | Everything SDK (DLL) | Everything's HTTP server plugin (unauthenticated) | `es.exe` subprocess |
| Tests / CI | pytest, GitHub Actions | None visible | None visible | None visible |

## Performance

`es.exe` (Everything's real-time NTFS index) vs. a naive filesystem walk, same query:

- **everything-mcp**: 220 ms avg (5 runs)
- **Naive walk of `C:\`**: 66,539 ms
- **~300x faster**

<details>
<summary>Reproduce this benchmark</summary>

```powershell
@'
import os, subprocess, time, 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 -
```
</details>

---

## Installation

### Prerequisites

1. **Windows** with [Everything](https://www.voidtools.com/) installed and **running**
2. **es.exe** (Everything's command-line interface) - included with Everything 1.5 alpha, or install separately:
   - `winget install voidtools.Everything.Cli`
   - `scoop install everything-cli`
   - `choco install es`
   - or download from [github.com/voidtools/es](https://github.com/voidtools/es/releases) and place it in your PATH
3. **Python 3.10+** or **uv**

### Run the server

```bash
uvx everything-mcp          # recommended, no install needed
pip install everything-mcp  # or via pip
```

From source:

```bash
git clone https://github.com/elis132/everything-mcp.git
cd everything-mcp && pip install -e ".[dev]"
```

### Add it to your client

Every client below uses the same MCP server definition:

```json
{
  "mcpServers": {
    "everything": {
      "command": "uvx",
      "args": ["everything-mcp"]
    }
  }
}
```

| Client | How to add it |
|---|---|
| **Claude Code** | `/plugin install everything-mcp@everything-mcp` (see [Quick start](#quick-start)), or `claude mcp add everything -- uvx everything-mcp` |
| **Claude Desktop** | Paste the JSON above into `%APPDATA%\Claude\claude_desktop_config.json` |
| **Codex CLI** | `codex mcp add everything -- uvx everything-mcp` |
| **Gemini CLI** | `gemini mcp add -s user everything uvx everything-mcp` |
| **Kimi CLI** | `kimi mcp add --transport stdio everything -- uvx everything-mcp` |
| **Qwen CLI** | `qwen mcp add -s user everything uvx everything-mcp` |
| **Cursor** | Paste the JSON above into Cursor's MCP settings UI |
| **Windsurf** | Paste the JSON above into `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
| **Any other MCP client** | Use the JSON above verbatim |

<details>
<summary>Using pip instead of uvx</summary>

```json
{ "mcpServers": { "everything": { "command": "everything-mcp" } } }
```

Or with explicit Python: `{"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` | Named Everything instance | `1.5a` |
| `EVERYTHING_MAX_RESULTS_CAP` | Hard cap on results per search (default `1000`) | `200` |

> Only set `EVERYTHING_INSTANCE` if you explicitly configured a named instance
> in Everything (Tools → Options → General → Instance). Most installs -
> including most Everything 1.5 installs - run on the **default** instance;
> setting this unnecessarily breaks the connection. If in doubt, leave it out.

```json
{
  "mcpServers": {
    "everything": {
      "command": "uvx",
      "args": ["everything-mcp"],
      "env": { "EVERYTHING_INSTANCE": "1.5a" }
    }
  }
}
```

---

## Tools

### 1. `everything_search` - the workhorse

| Parameter | Default | Description |
|---|---|---|
| `query` | *(required)* | Everything search query |
| `max_results` | 50 | 1-500 |
| `sort` | `date-modified-desc` | name, path, size, date-modified, date-created, extension (+ `-desc` variants) |
| `match_case` / `match_whole_word` / `match_regex` / `match_path` | false | Match modifiers |
| `offset` | 0 | Pagination offset |

**Query syntax:**

```
*.py                          all Python files
ext:py;js;ts                  multiple extensions
ext:py path:C:\Projects       Python files under a path
size:>10mb                    larger than 10 MB
size:1kb..1mb                 between 1 KB and 1 MB
dm:today / dm:last1week       modified today / in the last week
dc:2024                       created in 2024
"exact name.txt"              exact filename match
project1 | project2           OR search
!node_modules                 exclude a term
content:TODO                  files containing TODO (needs content indexing)
regex:^test_.*\.py$           regex search
parent:src ext:py             files directly inside 'src' folders
dupe:  /  empty:               duplicate filenames / empty folders
```

### 2. `everything_search_by_type` - category search

Categories: `audio`, `video`, `image`, `document`, `code`, `archive`, `executable`, `font`, `3d`, `data`

Parameters: `file_type` *(required)*, `query`, `path`, `max_results`, `sort`

### 3. `everything_find_recent` - what changed?

Periods: `1min` … `12hours`, `today`, `yesterday`, `1day` … `1year`

Parameters: `period` (default `1hour`), `path`, `extensions`, `query`, `max_results`

### 4. `everything_file_details` - deep inspection

Parameters: `paths` *(required, 1-20)*, `preview_lines` (0-200)

Returns full metadata; for directories, item count and listing; for text files with a preview, the first N lines.

### 5. `everything_count_stats` - quick analytics

Parameters: `query` *(required)*, `include_size` (default true), `breakdown_by_extension`

Count and size stats without listing every file - check scope before a big search.

---

## Examples

| Ask | Call |
|---|---|
| Python files modified today in my project | `everything_find_recent(period="today", extensions="py", path="C:\Projects\myapp")` |
| How much space do my log files use? | `everything_count_stats(query="ext:log", include_size=true, breakdown_by_extension=true)` |
| First 50 lines of a config file | `everything_file_details(paths=["C:\Projects\app\config.yaml"], preview_lines=50)` |
| Duplicate filenames in Documents | `everything_search(query='dupe: path:"C:\Users\me\Documents"')` |
| Images larger than 5MB | `everything_search(query="ext:jpg;png;gif size:>5mb")` |

---

## Troubleshooting

**"es.exe not found"** - Install [Everything](https://www.voidtools.com/) and [es.exe](https://github.com/voidtools/es/releases), or set `EVERYTHING_ES_PATH`.

**"Everything IPC window not found"** - Make sure Everything is running (check the system tray). If you set `EVERYTHING_INSTANCE`, try removing it - most installs don't need it. Everything Lite doesn't support IPC.

**No results for valid queries** - Confirm Everything's index has finished building, try the same query in Everything's GUI, and check the drive/path is included in Everything's index settings.

**Debugging:**

```bash
everything-mcp 2>everything-mcp.log                        # server logs
npx @modelcontextprotocol/inspector uvx everything-mcp      # MCP Inspector
```

---

## Development

```bash
pip install -e ".[dev]"   # install with dev dependencies
pytest                    # run tests
ruff check src/ tests/    # lint
```

Contributions welcome - see [CLAUDE.md](CLAUDE.md) for the architecture and design decisions. Areas of interest: direct named-pipe IPC, Everything SDK3 for 1.5, content search, file-watching, bookmark/tag support.

## License

MIT - see [LICENSE](LICENSE)

## Acknowledgments

[voidtools](https://www.voidtools.com/) for Everything, [Anthropic](https://anthropic.com/) for the Model Context Protocol, and the MCP community.

<!-- mcp-name: io.github.elis132/everything-mcp -->
