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.

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

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

fzf by Junegunn Choi - The amazing fuzzy finder
Model Context Protocol by Anthropic

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.

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

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

fzf by Junegunn Choi - The amazing fuzzy finder
Model Context Protocol by Anthropic

fzf MCP Server

fzf MCP Server

Features

Prerequisites

Installation

Using NPX (Recommended)

Global Installation

From Source

Configuration

Claude Desktop

Using NPX

Using Global Install

Custom fzf Path

VS Code

Available Tools

1. fuzzy_search_files

2. fuzzy_filter

3. fuzzy_search_content

Usage Examples

Example 1: Find Configuration Files

Example 2: Filter List of Options

Example 3: Search Code

How It Works

Fuzzy Matching Algorithm

Troubleshooting

fzf Not Found

No Results Found

Windows-Specific Issues

Development

Contributing

License

Acknowledgments

Links

fzf MCP Server

Features

Prerequisites

Installation

Using NPX (Recommended)

Global Installation

From Source

Configuration

Claude Desktop

Using NPX

Using Global Install

Custom fzf Path

VS Code

Available Tools

1. fuzzy_search_files

2. fuzzy_filter

3. fuzzy_search_content

Usage Examples

Example 1: Find Configuration Files

Example 2: Filter List of Options

Example 3: Search Code

How It Works

Fuzzy Matching Algorithm

Troubleshooting

fzf Not Found

No Results Found

Windows-Specific Issues

Development

Contributing

License

Acknowledgments

Links

1. `fuzzy_search_files`

2. `fuzzy_filter`

3. `fuzzy_search_content`

1. `fuzzy_search_files`

2. `fuzzy_filter`

3. `fuzzy_search_content`