File Search MCP 🔍

一个基于 FastMCP 的本地文件搜索 MCP Server。让 Claude 能够递归搜索项目文件内容，快速定位关键词。

功能

Tool（工具）

工具	说明
search_files(keyword, directory)	递归搜索文件内容中的关键词，返回匹配的文件路径、行号和内容
list_directory(path, pattern)	列出目录中的文件和子目录，支持 glob 过滤

Resource（资源）

资源 URI	说明
search://stats	搜索统计：累计搜索次数、最近 20 条搜索记录
config://settings	当前配置：文本扩展名白名单、跳过目录、文件大小上限等

特性

• 🧠 智能文件识别 — 白名单扩展名 + 二进制检测（null byte 扫描），避免搜索图片/压缩包/可执行文件
• 🚫 自动跳过无关目录 — 默认跳过 .git、node_modules、__pycache__、venv 等
• 📏 大文件保护 — 自动跳过大于 2MB 的文件，防止卡顿
• 🔤 大小写可选 — 默认不区分大小写，也可精确匹配
• 🎯 结果上限 — 默认最多返回 50 条，避免输出爆炸
• 📋 搜索历史 — 内存中保留最近 20 条搜索记录，可通过 Resource 查看

快速开始

环境要求

• Python 3.10+
• fastmcp >= 3.0

安装

# 克隆仓库
git clone https://github.com/rubber25ba/file-search-mcp.git
cd file-search-mcp

# 创建虚拟环境（推荐）
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 安装依赖
pip install fastmcp

本地测试

python server.py

在 Claude Code 中配置

在 Claude Code 的 settings.json 中添加：

{
  "mcpServers": {
    "file-search": {
      "command": "python",
      "args": ["C:/Users/YOUR_USERNAME/path/to/file-search-mcp/server.py"]
    }
  }
}

也可以在 Claude Code 中输入 /config 打开配置面板，选择 MCP Servers → Add，填写：

• Name: file-search
• Command: python
• Args: ["你的路径/file-search-mcp/server.py"]

配置完成后重启 Claude Code，试试：

• 「搜索 mcp-projects 目录下提到 FastMCP 的文件」
• 「列出桌面上所有的 .py 文件」

使用示例

示例 1：搜索代码中的关键词

用户：搜索当前项目里所有提到 "TODO" 的文件

Claude 调用 search_files(keyword="TODO", directory=".", glob_pattern="*.py")
→ 返回所有包含 TODO 的 Python 文件路径、行号和内容

示例 2：列出目录结构

用户：桌面上有哪些 Markdown 文件？

Claude 调用 list_directory(path="~/Desktop", glob_pattern="*.md")
→ 列出桌面上所有 .md 文件

示例 3：查看搜索统计

用户：我最近搜了什么？

Claude 读取 resource search://stats
→ 返回搜索次数和历史记录

配置说明

可以在 server.py 中修改以下常量：

配置	默认值	说明
MAX_RESULTS	50	单次搜索最多返回结果数
MAX_FILE_SIZE	2MB	跳过的文件大小阈值
SKIP_DIRS	.git, node_modules, ...	跳过搜索的目录名
TEXT_EXTENSIONS	.py, .js, .md, ...	文本文件扩展名白名单

项目结构

file-search-mcp/
├── server.py      # MCP Server 主程序（Tool + Resource）
└── README.md      # 本文件

技术栈

• FastMCP — Python MCP Server 框架
• MCP (Model Context Protocol) — Anthropic 推出的 AI 工具集成协议

License

MIT