How do I use File Search MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@File Search MCP find all TypeScript files modified in the last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

File Search MCP

by elad12390

Overview Schema Related Servers Score Discussions

TypeScript

Local

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

Related MCP server: MCP Smart Filesystem Server

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

Available Tools

4 tools

fuzzy_findA

USE WHEN YOU DON'T KNOW THE EXACT FILENAME. Fuzzy search that finds "UserController.ts" when you type "usrctl".

Ranked by match quality - best matches first. Perfect when you vaguely remember a filename or are exploring an unfamiliar codebase.

Much faster than glob with wildcards when you're guessing at names.

Examples: "userctrl" → UserController.ts, "jenkfile" → Jenkinsfile, "slacklib" → slackLib.groovy

ParametersJSON Schema

Name	Required	Description	Default
`reasoning`	Yes	Explain why you are using this tool - helps track search patterns and improve results
`query`	Yes	Fuzzy search query - type approximate file name, e.g. "usrctrl" finds "UserController.ts"
`path`	No	Directory to search in. Defaults to current working directory
`include_hidden`	No	Include hidden files and directories (dotfiles). Default: true
`detail_level`	No	How much info to return: "minimal" (paths only), "standard" (+ size/date), "full" (+ content preview)	standard

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that results are ranked by match quality and that it's faster than glob. However, it does not mention case sensitivity, whether it indexes files, or any potential side effects. It is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (~80 words), well-structured with a bolded usage guideline, followed by explanation, comparison, and examples. Every sentence is informative and earns its place, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and sibling tools, the description covers purpose, usage, comparison, and examples. It does not describe the output format in detail, but the detail_level parameter implies variable output. A minor gap exists, but overall it's sufficient for effective tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for the query parameter and explaining the detail_level options. This goes beyond bare descriptions, helping the agent choose appropriate values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs fuzzy filename search, using specific verbs like 'Fuzzy search' and resource 'filenames'. It distinguishes from siblings by contrasting with 'glob with wildcards' and mentioning alternatives like 'search_content' and 'search_files' implicitly through context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'USE WHEN YOU DON'T KNOW THE EXACT FILENAME' and highlights that it's faster than glob for guessing. Provides examples to illustrate typical use. Lacks explicit when-not-to-use guidance, but the context makes it clear that exact name searches should use other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_contentA

USE INSTEAD OF GREP. Search file contents with surrounding context - see matches in context without follow-up reads.

Respects .gitignore, skips binary files, smart case-sensitivity. Use for finding implementations, tracing function calls, or analyzing patterns across a codebase.

Use context_lines parameter to control how much surrounding code you see (default: 2 lines).

Examples: "slackSend|notification" in *.groovy, "webhook" across all files, "TODO" in src/

Requires ripgrep: brew install ripgrep (macOS) | apt install ripgrep (Ubuntu)

ParametersJSON Schema

Name	Required	Description	Default
`reasoning`	Yes	Explain why you are using this tool - helps track search patterns and improve results
`query`	Yes	Text or regex pattern to search for inside files, e.g. "TODO", "function.*export", "apiKey"
`path`	No	Directory to search in. Defaults to current working directory
`file_pattern`	No	Only search in files matching this pattern, e.g. ".ts", ".{js,jsx}"
`include_hidden`	No	Include hidden files and directories (dotfiles). Default: true
`ignore_gitignore`	No	Respect .gitignore rules and skip ignored files. Default: true
`exclude`	No	Additional patterns to exclude, e.g. ["node_modules", "dist", "*.log"]
`detail_level`	No	How much info to return: "minimal" (paths only), "standard" (+ size/date), "full" (+ content preview)	standard
`context_lines`	No	Number of lines to show before and after each match. Default: 2

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description effectively discloses key behaviors: respects .gitignore, skips binary files, smart case-sensitivity, and requires ripgrep. It also explains the context_lines parameter's effect. It could mention limitations or performance considerations for a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and is fairly concise. The inclusion of install commands and examples is helpful but could be slightly trimmed for conciseness. Overall, it is well-structured and not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters and no output schema, the description covers core usage but doesn't explain all parameters (e.g., detail_level) or the exact return format. It provides enough for basic use but lacks completeness for advanced scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline 3 is appropriate. The description adds value through query examples and context_lines default, but does not explain parameters like detail_level or exclude beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a tool for searching file contents with surrounding context, explicitly positioning it as an alternative to grep. The verb 'search' and resource 'file contents' are specific, and the description distinguishes it from siblings like fuzzy_find and search_files by focusing on content search with context lines.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'USE INSTEAD OF GREP' and provides specific use cases (finding implementations, tracing function calls). However, it does not contrast with sibling tools (fuzzy_find, search_files, tree) or provide explicit when-not-to-use conditions, which would make it a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_filesA

USE INSTEAD OF GLOB/FIND. Find files by pattern with built-in previews - eliminates follow-up read calls.

Respects .gitignore, skips binary files, filters by size/date, handles symlinks safely. Perfect for exploring unfamiliar codebases or analyzing build infrastructure.

Set detail_level="full" to get content previews without separate read calls.

Examples: ".yml" in .github/workflows/, "**/Jenkinsfile", "*.config.js"

ParametersJSON Schema

Name	Required	Description	Default
`reasoning`	Yes	Explain why you are using this tool - helps track search patterns and improve results
`pattern`	Yes	File name or glob pattern to match, e.g. ".ts", "test_", "src/*/.config.js"
`path`	No	Directory to search in. Defaults to current working directory
`include_hidden`	No	Include hidden files and directories (dotfiles). Default: true
`ignore_gitignore`	No	Respect .gitignore rules and skip ignored files. Default: true
`exclude`	No	Additional patterns to exclude, e.g. ["node_modules", "dist", "*.log"]
`detail_level`	No	How much info to return: "minimal" (paths only), "standard" (+ size/date), "full" (+ content preview)	standard
`modified_within`	No	Only find files modified within this time, e.g. "24h", "7d", "30m"
`min_size`	No	Only find files larger than this size, e.g. "1MB", "500KB", "1GB"

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description details behavioral traits: respects .gitignore, skips binary files, filters by size/date, handles symlinks safely, and notes that detail_level='full' provides content previews without extra calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two paragraphs plus examples, front-loaded with key purpose and usage advice. It is fairly concise, though minor restructuring could improve scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters and no output schema, the description covers core functionality, behavioral traits, and key parameter hints. It omits return format details, but the mention of previews and examples partially compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already describes each parameter well. The description adds value by explaining the effect of detail_level='full' and providing examples, but does not significantly augment the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Find files by pattern with built-in previews - eliminates follow-up read calls.' and contrasts with 'glob/find', clearly distinguishing the tool's purpose and scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises 'USE INSTEAD OF GLOB/FIND' and provides examples, but does not explicitly contrast with sibling tools like fuzzy_find, search_content, or tree, nor specify when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

treeA

USE INSTEAD OF LS/FIND FOR STRUCTURE. Visualize directory layout without multiple commands.

Get instant overview of project organization. Configurable depth prevents overwhelming output in deep repos.

Use this first when exploring a new codebase - shows you where to look before you start searching.

Perfect for: "Show me the project structure", "What's in repos/jenkins/", "How is src/ organized?"

ParametersJSON Schema

Name	Required	Description
`reasoning`	Yes	Explain why you need to see the directory structure
`path`	No	Directory to show. Defaults to current working directory
`depth`	No	Maximum depth to traverse. Default: 3
`include_hidden`	No	Include hidden files and directories (dotfiles). Default: false
`dirs_only`	No	Only show directories, not files. Default: false

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes configurable depth to prevent overwhelming output, default path behavior, and options for including hidden files or directories only. It implies read-only nature but does not explicitly state non-destructiveness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the key instruction "USE INSTEAD OF LS/FIND FOR STRUCTURE." It is informative but slightly verbose with multiple sections; could be more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters and no output schema, the description covers essential usage: purpose, when to use, and configuration. It lacks explanation of output format, but the tool's behavior (tree output) is conventionally understood.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema already provides for each parameter; it only gives usage context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states "USE INSTEAD OF LS/FIND FOR STRUCTURE" and "Visualize directory layout without multiple commands," specifying the verb and resource. It distinguishes from sibling tools like fuzzy_find, search_content, and search_files by focusing on directory structure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says "Use this first when exploring a new codebase," implying when to use. It also provides when-not-to-use by contrasting with other tools and gives example queries like "Show me the project structure."

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool targets a distinct search modality: fuzzy_find for approximate filename matching, search_content for grepping file contents, search_files for pattern-based file listing with previews, and tree for directory structure visualization. No overlap in purposes.

Naming Consistency5/5

All tools use lowercase snake_case with clear verbs or nouns (fuzzy_find, search_content, search_files, tree). The naming pattern is consistent and predictable, aiding agent selection.

Tool Count5/5

4 tools is well-scoped for a file search server. Each tool serves a core need (fuzzy name search, content grep, pattern file search, directory tree) without redundancy or excess.

Completeness5/5

The tool surface covers essential file exploration operations: fuzzy name finding, content search with context, pattern-based file discovery with previews, and project structure overview. No obvious gaps for typical use cases.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Maguyva
ai.maguyva
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code Analysis Coding Agents
23
gently
is.gently
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Code Analysis Developer Tools
1
sunub-obsidian-mcp-server
ai.smithery
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Note Taking Search Text Summarization
22
searchcode A
com.searchcode
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Search Code Analysis Version Control
62

Related MCP Servers

MCP Ripgrep Server
Search Command Line File Systems
mcollina
A
license
B
quality
D
maintenance
Provides ripgrep search capabilities to MCP clients like Claude, allowing high-performance text searches across files on your system.
Updated a year ago (2025-04-29 21:59 UTC)
5
1,018
74
MIT
MCP Smart Filesystem Server
File Systems Developer Tools Code Analysis
lofcz
A
license
A
quality
D
maintenance
Provides LLM-optimized filesystem access with intelligent file pagination for large files, lightning-fast ripgrep-powered code search with regex support, and security sandboxing to safely explore and search codebases.
Updated 10 months ago (2025-11-02 03:23 UTC)
7
9
1
MIT
fzf MCP Server
Search Developer Tools
danielsimonjr
A
license
Not graded
quality
A
maintenance
Enables fuzzy file searching, list filtering, and content searching using fzf's blazing-fast fuzzy matching algorithm. Self-contained with automatic fzf binary installation and cross-platform support.
Updated 6 days ago (2026-08-28 19:45 UTC)
35
3
MIT
fd-mcp
Developer Tools File Systems Command Line
thhart
A
license
Not graded
quality
C
maintenance
Provides fast file search capabilities using fd (a modern find alternative), enabling AI assistants to efficiently navigate codebases, search file contents with ripgrep, and execute commands on matched files.
Updated 9 months ago (2025-12-07 22:12 UTC)
1
MIT

Appeared in Searches

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/elad12390/file-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server