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:

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

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