fzf-mcp

snirt/fzf-mcp

3.2

If you are the rightful owner of fzf-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

fzf-mcp is a high-performance Model Context Protocol (MCP) server designed for efficient fuzzy search operations across files, content, and git repositories.

Tools
6
Resources
0
Prompts
0

fzf-mcp

A high-performance Model Context Protocol (MCP) server that provides fuzzy search capabilities for files, content, and git operations. Built in Go for speed and efficiency.

Features

  • Fuzzy File Search: Fast file finding with fuzzy matching and gitignore support
  • Content Search: Search through code with ripgrep integration and fuzzy filtering
  • Git Integration: Fuzzy search for branches, commits, and git-tracked files
  • Pluggable Architecture: Easily swap fuzzy matching implementations
  • High Performance: Built in Go with concurrent operations
  • Zero Runtime Dependencies: Single static binary

Installation

From Source

# Clone the repository
git clone https://github.com/snirt/fzf-mcp.git
cd fzf-mcp

# Build
make build

# Install (optional)
make install

Pre-built Binaries

Download the latest release for your platform from the releases page.

Usage

With Claude Desktop

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "fzf": {
      "command": "/path/to/fzf-mcp"
    }
  }
}

With Claude Code

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

{
  "mcpServers": {
    "fzf": {
      "type": "stdio",
      "command": "/path/to/fzf-mcp",
      "args": [],
      "env": {}
    }
  }
}

Configuration

Configure the fuzzy matcher via environment variable (in ~/.claude.json):

{
  "mcpServers": {
    "fzf": {
      "type": "stdio",
      "command": "/path/to/fzf-mcp",
      "args": [],
      "env": {
        "FZF_MCP_MATCHER": "sahilm"
      }
    }
  }
}

Available matchers:

  • sahilm (default): Optimized for filenames and code symbols

Available Tools

grep

Grep-style regex search through files with full regex support, case sensitivity, and context lines.

Parameters:

  • pattern (required): Regex pattern to search for (e.g., 'func.*Test', 'TODO|FIXME')
  • path (optional): Directory or file to search in (default: current directory)
  • case_insensitive (optional): Perform case-insensitive search (default: false)
  • context_before (optional): Number of lines to show before each match (like grep -B)
  • context_after (optional): Number of lines to show after each match (like grep -A)
  • limit (optional): Maximum number of matches (default: 20)
  • files_only (optional): Show only file names with matches (like grep -l, default: false)
  • max_line_len (optional): Maximum line length (default: 200)
  • file_pattern (optional): Glob pattern to filter files (e.g., '.go', '.{ts,tsx}')

Examples:

Find all TODO or FIXME comments: pattern="TODO|FIXME"
Find function definitions: pattern="func.*Test" file_pattern="*.go"
Find interface definitions: pattern="type.*interface" files_only=true
Case-insensitive search: pattern="error" case_insensitive=true
With context: pattern="YourString" context_before=2 context_after=2

fuzzy_find_files

Fuzzy search for files in a directory with gitignore support.

Parameters:

  • pattern (required): Fuzzy search pattern (e.g., 'main.go', 'test', 'src/comp')
  • path (optional): Root directory to search in (default: current directory)
  • limit (optional): Maximum number of results (default: 20)

Example:

Find files matching "config" in the current project

fuzzy_search_content

Search file contents and apply fuzzy filtering to results. Uses ripgrep if available.

Parameters:

  • query (required): Text to search for in file contents
  • path (optional): Root directory to search in (default: current directory)
  • pattern (optional): Fuzzy pattern to filter matching files
  • limit (optional): Maximum number of results (default: 20)
  • compact (optional): Return compact output (file:count) instead of full matches (default: false)
  • max_line_len (optional): Maximum line length for matches (default: 200)

Examples:

Search for "TODO" in files matching "controller"
Search for "YourString" with compact=true (saves tokens)
Search for "function.*interface" with limit=10

git_fuzzy_branches

Fuzzy search for git branches in a repository.

Parameters:

  • path (optional): Path to git repository (default: current directory)
  • pattern (optional): Fuzzy search pattern for branch names
  • limit (optional): Maximum number of results (default: 100)

git_fuzzy_files

Fuzzy search for git-tracked files in a repository.

Parameters:

  • pattern (required): Fuzzy search pattern for file names
  • path (optional): Path to git repository (default: current directory)
  • limit (optional): Maximum number of results (default: 100)

git_fuzzy_commits

Fuzzy search through git commit messages.

Parameters:

  • pattern (required): Fuzzy search pattern for commit messages
  • path (optional): Path to git repository (default: current directory)
  • limit (optional): Maximum number of results (default: 50)

Development

Prerequisites

  • Go 1.25 or later (recommended: use mise for version management)
  • (Optional) ripgrep for faster content search
  • (Optional) golangci-lint for linting
Installing Go with mise
# Install mise if not already installed
curl https://mise.run | sh

# Install Go (version specified in .mise.toml)
mise install

# Verify installation
mise exec -- go version  # Should show go1.25.4

Building

# Build for current platform
make build

# Build for all platforms
make build-all

# Run tests
make test

# Run with coverage
make test-coverage

# Format code
make fmt

# Lint code
make lint

Project Structure

fzf-mcp/
├── main.go              # MCP server entry point
├── config.go            # Configuration management
├── fuzzy/               # Fuzzy matching abstraction layer
│   ├── matcher.go       # FuzzyMatcher interface
│   └── sahilm.go        # sahilm/fuzzy implementation
├── tools/               # MCP tool implementations
│   ├── file_search.go   # File search tool
│   ├── content_search.go # Content search tool
│   ├── git_tools.go     # Git integration tools
│   └── gitignore.go     # Gitignore pattern matching
├── Makefile             # Build commands
├── README.md            # This file
└── CLAUDE.md            # Development guide for Claude Code

Adding a New Fuzzy Matcher

  1. Implement the FuzzyMatcher interface in fuzzy/
  2. Add the matcher type to fuzzy/matcher.go
  3. Update the NewMatcher function

Example:

// fuzzy/custom.go
type CustomMatcher struct{}

func (c *CustomMatcher) Match(pattern string, items []string) []Match {
    // Your implementation
}

func (c *CustomMatcher) MatchLimit(pattern string, items []string, limit int) []Match {
    // Your implementation
}

Performance

  • File Scanning: ~30ms for 60K files (using sahilm/fuzzy)
  • Startup Time: <20ms
  • Memory: ~5-15MB base footprint
  • Binary Size: ~5-15MB

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.