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)

Quick Start (npx)

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

Global Install

Then use in your config:

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

Usage with OpenCode

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

Tools

search_files

Find files by name or glob pattern.

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.

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.

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.

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

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

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

License

MIT