Everything Search MCP Server

Everything Search MCP Server

Windows、macOS、Linuxで高速なファイル検索機能を提供するMCPサーバーです。WindowsではEverything SDKを使用します。macOSでは組み込みのmdfindコマンドを使用します。Linuxではlocate／plocateコマンドを使用します。

Python 3.10以降が必要です。0.3.0以降、このサーバーはMCP Python SDK 2.xを基盤として構築されています。リリースノートについてはCHANGELOG.mdをご覧ください。

ツール

search

システム全体からファイルやフォルダーを検索します。検索機能と構文の対応状況はプラットフォームによって異なります。

• Windows：Everything SDKの全機能（構文ガイドは下記を参照）
• macOS：Spotlightデータベースを使用した基本的なファイル名および内容の検索
• Linux：locateデータベースを使用した基本的なファイル名の検索

引数はbaseオブジェクト（全プラットフォーム共通）とプラットフォーム固有のオブジェクトに分かれています。サーバーのツールスキーマには、現在のプラットフォームのオブジェクトのみが公開されます。

base（必須）：

• query（必須）：検索クエリ文字列。構文ガイドを参照してください。
• max_results（省略可）：返す結果の最大数（デフォルト：100、範囲：1～1000）

windows_params（省略可、Windowsのみ）：

• match_path：ファイル名のみでなく、フルパスを照合します（デフォルト：false）
• match_case：大文字と小文字を区別する検索を有効にします（デフォルト：false）
• match_whole_word：単語全体のみを照合します（デフォルト：false）
• match_regex：正規表現検索を有効にします（デフォルト：false）
• sort_by：結果の並べ替え順（デフォルト：1）。利用可能なオプション：

  - 1: Sort by filename (A to Z)
  - 2: Sort by filename (Z to A)
  - 3: Sort by path (A to Z)
  - 4: Sort by path (Z to A)
  - 5: Sort by size (smallest first)
  - 6: Sort by size (largest first)
  - 7: Sort by extension (A to Z)
  - 8: Sort by extension (Z to A)
  - 11: Sort by creation date (oldest first)
  - 12: Sort by creation date (newest first)
  - 13: Sort by modification date (oldest first)
  - 14: Sort by modification date (newest first)

mac_params（省略可、macOSのみ）：

• search_directory：検索対象をディレクトリに限定します（mdfind -onlyin）。~は展開されます。ディレクトリは存在している必要があります。
• literal_query：クエリをSpotlightのリテラルクエリ文字列として扱います（-literal）
• interpret_query：Spotlightメニューに入力されたものとしてクエリを解釈します（-interpret）
• live_updates：未対応です。mdfind -liveは終了しないため、設定するとエラーが返されます。

デフォルトでは、クエリはファイル名検索（mdfind -name）として扱われます。literal_queryまたはinterpret_queryを設定すると、クエリはそのままSpotlightに渡されます。この場合、mdfindがオプションとして読み取ってしまうため、クエリを-で始めることはできません。

linux_params（省略可、Linuxのみ）：

• ignore_case：大文字と小文字を区別しない検索（-i、デフォルト：true）
• regex_search：クエリを正規表現として扱います（デフォルト：false）
• existing_files：現在も存在するファイルのみを一覧表示します（-e、デフォルト：true）
• count_only：一致数のみを返します（-c、デフォルト：false）

例：

{
  "base": {"query": "*.py", "max_results": 50},
  "windows_params": {"sort_by": 6}
}

{
  "base": {"query": "ext:py datemodified:today", "max_results": 10}
}

{
  "base": {"query": "ENABLE", "max_results": 50},
  "mac_params": {"search_directory": "/Users/me/code/myrepo"}
}

各結果には次の情報が含まれます。

• Path：フルパス
• Filename：ファイル名。拡張子がある場合は括弧内に表示されます
• Size：バイト単位のサイズ
• Created、Modified、Accessed：タイムスタンプ。取得できない場合はN/A

検索に失敗した場合（引数が無効、Everythingが起動していない、検索コマンドに30秒を超える時間がかかる場合など）、ツールはエラー結果（isError: true）を返します。そのテキストはSearch failed:で始まります。

WindowsでEverythingから読み取れない一致項目がある場合（タイムスタンプが破損したファイルなど）、読み取り可能な結果が返され、出力の末尾にWarning: N matching result(s) could not be read and were omitted.が表示されます。

検索構文ガイド

各プラットフォーム（Windows、macOS、Linux）で対応している検索構文の詳細については、SEARCH_SYNTAX.mdをご覧ください。

前提条件

Windows

1. Everything 検索ユーティリティ：
   • https://www.voidtools.com/ からダウンロードしてインストールします
   • Everything サービスが実行中であることを確認してください
2. Everything SDK：
   • https://www.voidtools.com/support/everything/sdk/ からダウンロードします
   • SDK ファイルをシステム上の任意の場所に展開します
   • 同じ SDK DLL（Everything64.dll）は Everything 1.5 でも動作します

Linux

1. locate または plocate コマンドをインストールして初期化します：
   • Ubuntu/Debian：sudo apt-get install plocate または sudo apt-get install mlocate
   • Fedora：sudo dnf install mlocate
2. インストール後、データベースを更新します：
   • plocate の場合：sudo updatedb
   • mlocate の場合：sudo /etc/cron.daily/mlocate

macOS

追加のセットアップは不要です。サーバーは組み込みの mdfind コマンドを使用します。

インストール

uv を使用する場合（推奨）

uv を使用する場合、特別なインストールは不要です。 uvx を使って mcp-server-everything-search を直接実行します。

0.2.x からアップグレードする場合： uvx がキャッシュ済みの 0.2.1 を使い続けることがあり、その場合、現在の MCP SDK では起動に失敗します（'Server' object has no attribute 'list_resources'。詳しくは #39 を参照してください）。最新バージョンで一度実行し、キャッシュを更新してください：

uvx mcp-server-everything-search@latest

PIP を使用する場合

または、pip を使って mcp-server-everything-search をインストールできます：

pip install -U mcp-server-everything-search

インストール後、スクリプトとして次のように実行できます：

python -m mcp_server_everything_search

設定

Windows

EVERYTHING_SDK_PATH に Everything SDK の Everything64.dll のフルパスを設定します。この設定は必須です。未設定の場合、またはファイルを指していない場合、サーバーは起動時に変数名を示すエラーを出して停止します。

EVERYTHING_SDK_PATH=C:\path\to\Everything-SDK\dll\Everything64.dll

Linux と macOS

追加の設定は不要です。

ツール名

既定では、ツール名は search です。クライアント内で別の MCP サーバーのツール名と重複する場合は、名前を変更してください：

EVERYTHING_SEARCH_TOOL_NAME=everything_search

名前には英字、数字、_、- を使用できます（1～64 文字）。無効な値を指定すると、サーバーは起動時に停止します。

Claude Code での使用方法

Windows：

claude mcp add everything-search -e EVERYTHING_SDK_PATH="C:\path\to\Everything-SDK\dll\Everything64.dll" -- uvx mcp-server-everything-search

Linux と macOS：

claude mcp add everything-search -- uvx mcp-server-everything-search

Claude Desktop での使用方法

プラットフォームに応じて、以下の設定のいずれかを claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "everything-search": {
      "command": "uvx",
      "args": ["mcp-server-everything-search"],
      "env": {
        "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
      }
    }
  }
}

{
  "mcpServers": {
    "everything-search": {
      "command": "python",
      "args": ["-m", "mcp_server_everything_search"],
      "env": {
        "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
      }
    }
  }
}

{
  "mcpServers": {
    "everything-search": {
      "command": "uvx",
      "args": ["mcp-server-everything-search"]
    }
  }
}

{
  "mcpServers": {
    "everything-search": {
      "command": "python",
      "args": ["-m", "mcp_server_everything_search"]
    }
  }
}

デバッグ

MCP inspector を使ってサーバーをデバッグできます。uvx でインストールした場合：

npx @modelcontextprotocol/inspector uvx mcp-server-everything-search

特定のディレクトリにパッケージをインストールした場合や、開発中の場合は、次のようにします：

git clone https://github.com/mamertofabian/mcp-everything-search.git
cd mcp-everything-search
npx @modelcontextprotocol/inspector uv run mcp-server-everything-search

サーバーログを表示するには：

Linux/macOS：

tail -f ~/.config/Claude/logs/mcp*.log

Windows（PowerShell）：

Get-Content -Path "$env:APPDATA\Claude\logs\mcp*.log" -Tail 20 -Wait

開発

ローカルで開発する場合、変更をテストする方法は 2 つあります：

1. MCP inspector を実行して変更をテストします。実行方法はデバッグを参照してください。

2. Claude デスクトップアプリを使ってテストします。以下を claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "everything-search": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-everything-search",
        "run",
        "mcp-server-everything-search"
      ],
      "env": {
        "EVERYTHING_SDK_PATH": "path/to/Everything-SDK/dll/Everything64.dll"
      }
    }
  }
}

テストとチェック

uv run pytest
uv run ruff check
uv run pyright

CI では Windows、macOS、Linux（Python 3.10 および 3.13）でテストを実行します。コード変更は manifests/ 内の MAID マニフェストとして計画します。CLAUDE.md/AGENTS.md を参照し、プルリクエストを作成する前に scripts/maid validate を実行してください。

ライセンス

この MCP サーバーは MIT License のもとでライセンスされています。つまり、MIT License の利用規約に従うことを条件として、ソフトウェアを自由に使用、変更、配布できます。詳しくは、プロジェクトリポジトリの LICENSE ファイルを参照してください。

免責事項

このプロジェクトは、Everything 検索ユーティリティの開発元である voidtools とは提携しておらず、voidtools による承認や支援も受けていません。公開されている Everything SDK を利用する独立したプロジェクトです。