MCP 服务器

fzf MCP Server

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.

README

fzf MCP Server

Model Context Protocol (MCP) server for fzf, the command-line fuzzy finder. Enables fuzzy file searching, list filtering, and content searching through MCP.

Features

n🎁 Self-Contained: fzf binary automatically downloaded and bundled during installation - no manual setup required!

Fuzzy File Search: Search for files recursively using fzf's fuzzy matching
List Filtering: Filter any list of items with fuzzy matching
Content Search: Search within file contents using fuzzy matching
Fast & Efficient: Leverages fzf's blazing-fast fuzzy finder
Auto-Install: fzf binary downloads automatically on npm install
Cross-Platform: Works on Windows, macOS, and Linux

Prerequisites

None! fzf binary is automatically downloaded and bundled during npm install. The package is completely self-contained.

Installation

Using NPX (Recommended)

No installation required:

npx @danielsimonjr/fzf-mcp

Global Installation

npm install -g @danielsimonjr/fzf-mcp

From Source

git clone https://github.com/danielsimonjr/fzf-mcp.git
cd fzf-mcp
npm install
chmod +x index.js

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

Using NPX

{
  "mcpServers": {
    "fzf": {
      "command": "npx",
      "args": ["-y", "@danielsimonjr/fzf-mcp"]
    }
  }
}

Using Global Install

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

Custom fzf Path

If fzf is not in your PATH, set the FZF_PATH environment variable:

{
  "mcpServers": {
    "fzf": {
      "command": "npx",
      "args": ["-y", "@danielsimonjr/fzf-mcp"],
      "env": {
        "FZF_PATH": "C:\\path\\to\\fzf.exe"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "fzf": {
      "command": "npx",
      "args": ["-y", "@danielsimonjr/fzf-mcp"]
    }
  }
}

Available Tools

1. `fuzzy_search_files`

Search for files using fzf's fuzzy matching.

Parameters:

query (required): Fuzzy search query (e.g., "readme", "index.js")
directory (optional): Starting directory (default: current directory)
maxResults (optional): Maximum number of results (default: 50)
caseSensitive (optional): Enable case-sensitive matching (default: false)
exact (optional): Enable exact matching instead of fuzzy (default: false)

Example:

{
  "query": "readme",
  "directory": "C:\\projects",
  "maxResults": 10
}

2. `fuzzy_filter`

Filter a list of items using fzf's fuzzy matching algorithm.

Parameters:

items (required): Array of strings to filter
query (required): Fuzzy search query
maxResults (optional): Maximum number of results (default: 50)
caseSensitive (optional): Enable case-sensitive matching (default: false)
exact (optional): Enable exact matching (default: false)

Example:

{
  "items": ["apple", "banana", "orange", "grape", "pineapple"],
  "query": "app",
  "maxResults": 5
}

3. `fuzzy_search_content`

Search within file contents using fuzzy matching.

Parameters:

query (required): Content search query
directory (optional): Directory to search (default: current directory)
filePattern (optional): File pattern to search (default: "*")
maxResults (optional): Maximum number of results (default: 50)
caseSensitive (optional): Enable case-sensitive matching (default: false)

Example:

{
  "query": "function",
  "directory": "C:\\projects\\myapp",
  "filePattern": "*.js",
  "maxResults": 20
}

Usage Examples

Example 1: Find Configuration Files

Tell Claude:

Use fzf to search for all configuration files (config, .env, settings) in my project directory.

Claude will use the fuzzy_search_files tool to find matching files.

Example 2: Filter List of Options

Tell Claude:

I have this list of packages: [express, react, vue, angular, svelte, next, nuxt, remix]
Use fzf to filter for packages containing "re"

Claude will use the fuzzy_filter tool to return: express, react, svelte

Example 3: Search Code

Tell Claude:

Search for all occurrences of "async function" in my TypeScript files.

Claude will use the fuzzy_search_content tool to find matches.

How It Works

fzf-mcp uses fzf's --filter mode to provide non-interactive fuzzy matching:

File Search: Generates a file list from the directory and pipes it to fzf
List Filter: Pipes the provided list to fzf for filtering
Content Search: Uses grep/findstr to find content, then filters with fzf

All matching is done server-side, returning only the filtered results to Claude.

Fuzzy Matching Algorithm

fzf uses a sophisticated fuzzy matching algorithm that:

Matches characters in order but not necessarily consecutive
Scores matches based on character positions
Prioritizes matches at word boundaries
Supports exact matching with the exact option

Examples:

Query "abc" matches: "abc", "a_b_c", "aXbXc", "AnyBigCat"
Query "^music" matches files starting with "music"
Query "mp3$" matches files ending with "mp3"

Troubleshooting

fzf Not Found

Error: Failed to execute fzf: spawn fzf ENOENT

Solution:

Ensure fzf is installed: fzf --version
Add fzf to your PATH, or set FZF_PATH environment variable in MCP config

No Results Found

Causes:

Query doesn't match any items
Directory doesn't exist or is empty
Insufficient permissions to read directory

Solutions:

Try a less specific query
Verify directory path
Check file permissions

Windows-Specific Issues

Issue: File listing commands fail

Solution: The server tries multiple commands (dir, find, ls) and uses the first that succeeds. Ensure at least one is available in your PATH.

Development

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

# Install dependencies
npm install

# Make executable
chmod +x index.js

# Test locally
node index.js