file-search-mcp

A blazingly fast MCP server for searching files in large codebases and monorepos.

Why This Exists

Standard tools like grep and find are painfully slow on large codebases. They don't respect .gitignore, they follow symlink loops, and they flood your terminal with irrelevant results from node_modules.

file-search-mcp fixes all that:

Problem	Solution
grep is slow on big repos	Uses ripgrep (100x faster)
find follows symlink loops	Built-in loop detection
Results flood the terminal	Smart token-based truncation
Binary files pollute results	Auto-detected and skipped
Need to remember complex flags	Simple, intuitive parameters
No context for matches	Configurable context lines
Case sensitivity confusion	Smart case by default

Installation

Prerequisites

• Node.js 18+
• ripgrep (for content search)

# Install ripgrep
brew install ripgrep    # macOS
apt install ripgrep     # Ubuntu
choco install ripgrep   # Windows

Quick Start (npx)

No installation required! Just add to your MCP client config:

{
  "mcpServers": {
    "file-search": {
      "command": "npx",
      "args": ["-y", "file-search-mcp"]
    }
  }
}

Global Install

npm install -g file-search-mcp

Then use in your config:

{
  "mcpServers": {
    "file-search": {
      "command": "file-search-mcp"
    }
  }
}

Usage with Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "file-search": {
      "command": "npx",
      "args": ["-y", "file-search-mcp"]
    }
  }
}

Usage with OpenCode

Add to your OpenCode config (~/.config/opencode/config.json):

{
  "mcp": {
    "file-search": {
      "type": "local",
      "command": ["npx", "-y", "file-search-mcp"]
    }
  }
}

Tools

search_files

Find files by name or glob pattern.

"Find all TypeScript files"
→ search_files(pattern: "*.ts")

"Find config files modified today"
→ search_files(pattern: "*.config.*", modified_within: "24h")

"Find large log files"
→ search_files(pattern: "*.log", min_size: "10MB")

Parameters:

• reasoning (required) - Why you're searching
• pattern (required) - Glob pattern like *.ts, src/**/*.js
• path - Directory to search (default: current dir)
• include_hidden - Include dotfiles (default: true)
• ignore_gitignore - Respect .gitignore (default: true)
• exclude - Extra patterns to skip
• detail_level - minimal | standard | full
• modified_within - Only recent files, e.g., 24h, 7d
• min_size - Only large files, e.g., 1MB

search_content

Find text or regex patterns inside files.

"Find all TODO comments"
→ search_content(query: "TODO")

"Find API endpoints"
→ search_content(query: "app\.(get|post|put|delete)", file_pattern: "*.ts")

"Find hardcoded secrets"
→ search_content(query: "apiKey|secret|password")

Parameters:

• reasoning (required) - Why you're searching
• query (required) - Text or regex to find
• path - Directory to search (default: current dir)
• file_pattern - Only search matching files
• include_hidden - Include dotfiles (default: true)
• ignore_gitignore - Respect .gitignore (default: true)
• exclude - Extra patterns to skip
• detail_level - minimal | standard | full
• context_lines - Lines around matches (default: 2)

fuzzy_find

Fuzzy search when you don't remember exact names.

"Find the user controller"
→ fuzzy_find(query: "usrctrl")

"Find that API routes file"
→ fuzzy_find(query: "apirts")

Parameters:

• reasoning (required) - Why you're searching
• query (required) - Fuzzy search terms
• path - Directory to search (default: current dir)
• include_hidden - Include dotfiles (default: true)
• detail_level - minimal | standard | full

tree

Visualize directory structure.

"Show me the project structure"
→ tree(depth: 3)

"What's in the src folder?"
→ tree(path: "src", depth: 2)

Parameters:

• reasoning (required) - Why you need this view
• path - Directory to show (default: current dir)
• depth - How deep to traverse (default: 3)
• include_hidden - Show dotfiles (default: false)
• dirs_only - Only show directories (default: false)

Detail Levels

Level	What You Get
minimal	Just paths - fast, low tokens
standard	Paths + size + modified date
full	Everything + content preview/matches

Smart Features

Smart Case

Searches are case-insensitive by default, but become case-sensitive if your query contains uppercase letters. This matches how VS Code, ripgrep, and most modern tools work.

Token Limiting

Results are automatically truncated to ~100k tokens to prevent overwhelming responses. You'll see a warning if truncation occurred.

Binary Detection

Binary files (images, executables, archives, etc.) are automatically skipped to keep results clean and relevant.

Symlink Safety

Symlinks are followed, but loops are detected and prevented. No more infinite traversal!

Default Excludes

These directories are always skipped unless you override:

• node_modules
• .git
• dist, build
• coverage
• .next, .nuxt
• __pycache__, .pytest_cache
• venv, .venv
• target (Rust)
• vendor (Go)

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch    # Watch mode

Metrics

All tool calls are tracked locally for development analysis. Metrics include:

• Tool usage counts
• Search patterns and queries
• Response times
• Error and truncation rates
• Reasoning text for understanding use cases

# View metrics summary
npm run metrics

# View last 50 raw calls
npm run metrics:raw

# Clear all metrics
npm run metrics:clear

Metrics are stored at ~/.file-search-mcp/metrics.json

License

MIT