fd-mcp

A Model Context Protocol (MCP) server that provides fast file search capabilities using fd, a modern alternative to the traditional find command.

What is fd-mcp?

fd-mcp bridges fd with AI assistants like Claude Code through the Model Context Protocol. It exposes fd's powerful file search capabilities as MCP tools, enabling AI assistants to efficiently navigate and search codebases.

Why fd?

fd offers significant advantages over traditional file search tools:

• Blazing Fast: Written in Rust, fd is often 5-10x faster than find for typical searches
• Recursive by Default: Searches directories recursively without special flags (use max_depth to limit)
• User-Friendly Syntax: Simple, intuitive patterns instead of cryptic flags (fd pattern vs find -name "*pattern*")
• Smart Defaults: Automatically respects .gitignore and skips hidden files/directories
• Colorized Output: Enhanced readability with syntax highlighting
• Parallel Execution: Leverages multiple CPU cores for faster searches
• Regex Support: Built-in regex pattern matching without complex syntax

Use Cases

This MCP server is particularly useful for:

• Codebase Navigation: Quickly locate files by name, extension, or pattern across large projects
• Project Analysis: Find all files of a specific type (e.g., all Python test files, all configuration files)
• Code Exploration: Help AI assistants understand project structure by efficiently listing directories and files
• Pattern Matching: Search for files using regex patterns (e.g., find all migration files, test suites)
• Selective Searches: Filter by file type, depth, or exclude specific patterns
• Performance: Fast searches even in monorepos or large codebases with thousands of files

Prerequisites

Install fd:

# Ubuntu/Debian
sudo apt install fd-find

# macOS
brew install fd

# Arch
pacman -S fd

Install ripgrep (required for fd_search_content tool):

# Ubuntu/Debian
sudo apt install ripgrep

# macOS
brew install ripgrep

# Arch
pacman -S ripgrep

# Or download from: https://github.com/BurntSushi/ripgrep/releases

Installation

cd fd-mcp
pip install -e .

Usage with Claude Code

Add to your Claude Code MCP settings (~/.claude.json):

{
  "mcpServers": {
    "fd": {
      "command": "fd-mcp"
    }
  }
}

Or run directly:

{
  "mcpServers": {
    "fd": {
      "command": "python",
      "args": ["-m", "fd_mcp.server"],
      "cwd": "/home/th/dev/os/fd-mcp"
    }
  }
}

🚀 Claude Code Integration Best Practices

Once configured, Claude Code will have access to all fd-mcp tools. Here's how to get the most out of them:

Quick Start Commands

The project includes helpful slash commands to get started:

• /find-py - Find all Python files (demonstrates fd_search)
• /search-code - Search code patterns (demonstrates fd_search_content)
• /recent - Show recently modified files (demonstrates fd_recent_files)
• /count-files - Count files by type (demonstrates fd_count)
• /demo-mcp - Run a full demonstration of all tools

Tool Selection Guide

When Claude Code needs to find files:

• ✅ Use: mcp__fd__fd_search(pattern=".*", path=".", extension="py")
• ❌ Instead of: bash find . -name "*.py"
• Why: 5-10x faster, respects .gitignore automatically

When Claude Code needs to search code:

• ✅ Use: mcp__fd__fd_search_content(search_pattern="TODO", extension="py")
• ❌ Instead of: bash find . -exec grep "TODO" {} \;
• Why: 10-100x faster, single operation, shows context

When Claude Code needs to find recent changes:

• ✅ Use: mcp__fd__fd_recent_files(hours=24)
• ❌ Instead of: bash find . -mtime -1
• Why: Intuitive time params, faster execution

Performance Benefits

The tools are optimized for AI assistant workflows:

Learning Resources

• See CLAUDE.md for comprehensive usage patterns and examples
• Check .claude/commands/ for ready-to-use slash commands
• Review tool descriptions in Claude Code for quick reference

Tools

fd_search

Replaces: find, locate commands

Search for files and directories using fd (5-10x faster than find). Searches recursively by default through all subdirectories.

fd_search_content ⭐

Replaces: find -exec grep, find | xargs grep commands

Search for content within files using fd+ripgrep. This is the key tool that replaces find . -exec grep pattern {} \; style commands.

Note: Requires ripgrep (rg) to be installed.

fd_exec

Replaces: find -exec, find | xargs commands

Execute a command on files found by fd. Use {} as placeholder for filename.

fd_recent_files

Replaces: find -mtime, find -newermt commands

Find recently modified files.

fd_count

Replaces: find | wc -l commands

Count files matching a pattern.

Examples

Basic File Search

Find all Python files (recursively):

fd_search(pattern=".*", path=".", extension="py")

Find test files in entire project tree:

fd_search(pattern="test_.*", path=".", extension="py")

List directories only (limit to 2 levels deep):

fd_search(pattern=".*", path=".", type="d", max_depth=2)

Search only current directory (no recursion):

fd_search(pattern=".*", path=".", extension="py", max_depth=1)

Content Search (replaces find -exec grep)

Find "TODO" in all Python files:

fd_search_content(search_pattern="TODO", extension="py")

Find "import React" in JavaScript/TypeScript files with context:

fd_search_content(
    search_pattern="import.*React",
    extension="tsx",
    context_lines=2
)

Find error handling in specific directory:

fd_search_content(
    search_pattern="try.*except",
    path="src/",
    extension="py"
)

Execute Commands on Files

Count lines in all Python files:

fd_exec(command="wc -l {}", pattern=".*", path=".", extension="py")

Format all JavaScript files:

fd_exec(command="prettier --write {}", pattern=".*", path=".", extension="js")

Find Recent Changes

Files modified in last 2 hours:

fd_recent_files(hours=2)

Recent Python files modified in last day:

fd_recent_files(hours=24, extension="py")

Command Replacements

License

This project is licensed under the MIT License - see the LICENSE file for details.