MCP Server - File Search Tool 🗂️

MCP サーバー - ファイル検索ツール 🗂️

MCP（Model Context Protocol）プロトコルを介して、強力なファイルシステムの検索・調査機能を提供する MCP サーバーです。このツールを使うと、ディレクトリの一覧表示、ファイル名の検索、ファイル内容の読み取り（PDF および DOCX を含む）、コンテキスト付きの正規表現ベースの内容検索ができます。

機能

• ファイルパスの一覧表示：幅優先または深さ優先で一覧表示できます。ページングや階層の深さも指定できます。
• ファイル名の検索：正規表現ベースでファイル名を検索できます。
• ファイルの読み取り：文字数の上限を任意で指定して、テキスト、PDF、DOCX ファイルを読み取れます。
• ファイル内容の検索：コンテキスト行数を設定して、正規表現ベースで内容を検索できます。
• 許可パス：設定したディレクトリ内のみをサーバーが参照・検索するよう制限できます。
• 除外パス：機密性の高いディレクトリへのアクセスを防止できます。
• 隠しファイルの非表示：任意で、ドットから始まるファイルやディレクトリを無視できます。
• パスマスキング：プライバシー保護のため、設定したパスの各要素をトークンに置き換えます。

前提条件

• Python 3.10 以降
• uv - 高速な Python パッケージマネージャー

インストール

1. リポジトリをクローンします：

git clone https://github.com/RJTPP/mcp-server-file-search-tool
cd mcp-server-file-search-tool

2. 仮想環境を作成し、依存関係をインストールします：

uv sync

サーバーの起動

サーバーを起動します（デフォルトポート：6277）：

uv run server.py

Claude Desktop との連携

このサーバーを Claude Desktop に追加するには：

mcp install server.py --name "File Search Tool"

または、claude_desktop_config.json に手動で追加します：

{
  "mcpServers": {
    "File Search Tool": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-sever-file-search-tool/",
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "server.py"
      ]
    }
  }
}

設定

1. サンプル設定をコピーします：

   cp config_example.json config.json

2. config.json を編集してカスタマイズします：

{
  "DEFAULT_TIME_LIMIT": 10,
  "HIDE_HIDDEN_FILES": true,
  "HOST": "127.0.0.1",
  "PORT": 6277,
  "ALLOWED_PATHS": [
    "/path/to/allowed/directory"
  ],
  "EXCLUDE_PATHS": [
    "/path/to/excluded/directory"
  ],
  "PATH_MASKER": {
    "ENABLED": true,
    "MODE": "segment",
    "MASK_TOKEN": "MASK",
    "LOOK_FOR": [
      "path_to_mask"
    ]
  }
}

必須フィールド

• ALLOWED_PATHS は必須です。許可するパスを 1 つ以上設定しないと、サーバーは起動しません。

設定フィールドの説明

フィールド	型	説明
DEFAULT_TIME_LIMIT	int	検索の最大実行時間（秒）。
HIDE_HIDDEN_FILES	bool	true の場合、. で始まるファイルやディレクトリを無視します。
HOST	string	サーバーがバインドする IP アドレス（例："127.0.0.1"）。
PORT	int	リッスンするポート番号（例：6277）。
ALLOWED_PATHS	list[string]	**必須。**サーバーがアクセスおよび検索を許可されるディレクトリ。
EXCLUDE_PATHS	list[string]	許可パス内にある場合も含め、明示的にアクセスを禁止するディレクトリ。
PATH_MASKER	object	プライバシー保護のための任意のマスキング設定。
PATH_MASKER.ENABLED	bool	パスマスキングを有効または無効にします。
PATH_MASKER.MODE	"segment" または "prefix"	マスキングモード："segment" は一致する各要素を置き換え、"prefix" はパスのプレフィックス全体をマスキングします。
PATH_MASKER.MASK_TOKEN	string	一致したパスの各要素を置き換えるトークン（例："MASK"）。
PATH_MASKER.LOOK_FOR	list[string]	フルパス内で見つかった場合にマスキングするパスの各要素のリスト。

セキュリティ

警告

このサーバーには、認証や暗号化が実装されていません。
ローカルでの個人利用のみを想定しています。 適切なセキュリティ対策を追加せずに、信頼できないネットワークにサーバーを公開したり、本番環境で使用したりしないでください。

ライセンス

このプロジェクトは、MIT License のもとで公開されています。

MIT License の条件に従って、このソフトウェアを自由に使用、変更、配布できます。詳細な利用条件については LICENSE ファイルを参照してください。