Skip to main content
Glama

fzf MCP Server

by danielsimonjr
GitHub
JavaScript
MIT License
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

fzf MCP Server

NPM License MCP

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:

  1. File Search: Generates a file list from the directory and pipes it to fzf

  2. List Filter: Pipes the provided list to fzf for filtering

  3. 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:

  1. Ensure fzf is installed: fzf --version

  2. 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

Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Test thoroughly

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

Links

Made with ❤️ for the MCP community

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

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.

  1. Features
    1. Prerequisites
      1. Installation
        1. Using NPX (Recommended)
        2. Global Installation
        3. From Source
      2. Configuration
        1. Claude Desktop
        2. VS Code
      3. Available Tools
        1. 1. fuzzy_search_files
        2. 2. fuzzy_filter
        3. 3. fuzzy_search_content
      4. Usage Examples
        1. Example 1: Find Configuration Files
        2. Example 2: Filter List of Options
        3. Example 3: Search Code
      5. How It Works
        1. Fuzzy Matching Algorithm
          1. Troubleshooting
            1. fzf Not Found
            2. No Results Found
            3. Windows-Specific Issues
          2. Development
            1. Contributing
              1. License
                1. Acknowledgments
                  1. Links

                    New MCP Servers

                    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/danielsimonjr/fzf-mcp'

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