Feroxbuster

A Model Context Protocol (MCP) server for feroxbuster - a fast, simple, recursive content discovery tool written in Rust.

Overview

This MCP server enables AI assistants to control feroxbuster scans on a remote Kali Linux system via SSH. It provides a complete interface for web content discovery with support for:

• Directory and file brute-forcing with customizable wordlists
• Recursive scanning with configurable depth
• Flexible filtering (status codes, response size, word count, line count)
• Rate limiting, auto-tuning, and auto-bail features
• Background scans with real-time progress monitoring
• Resume capability from state files
• Multiple output formats (text, JSON, URLs)

Prerequisites

• Node.js 18+
• SSH access to a Kali Linux system (or any system with feroxbuster installed)
• SSH key authentication configured for passwordless access (recommended)
• feroxbuster installed on the remote system

Installation

git clone https://github.com/schwarztim/sec-feroxbuster-mcp.git
cd sec-feroxbuster-mcp
npm install
npm run build

Configuration

Claude Desktop / Claude Code

Add the server to your MCP configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "feroxbuster": {
      "command": "node",
      "args": ["/path/to/sec-feroxbuster-mcp/dist/index.js"],
      "env": {
        "KALI_HOST": "kali"
      }
    }
  }
}

Claude Code (~/.claude/user-mcps.json):

{
  "feroxbuster": {
    "command": "node",
    "args": ["/path/to/sec-feroxbuster-mcp/dist/index.js"],
    "env": {
      "KALI_HOST": "kali"
    }
  }
}

Environment Variables

Variable	Description	Default
KALI_HOST	SSH hostname for the remote system with feroxbuster	kali

SSH Setup

Ensure SSH key authentication is configured:

# Generate key if needed
ssh-keygen -t ed25519 -C "feroxbuster-mcp"

# Copy to remote host
ssh-copy-id kali

# Test connection
ssh kali "feroxbuster --version"

Available Tools

feroxbuster_scan

Start a directory/file discovery scan against a target URL.

Parameters:

Parameter	Type	Description
url	string	(required) Target URL to scan
wordlist	string	Path to wordlist on remote system
extensions	string[]	File extensions to check (e.g., ["php", "html", "js"])
recursion_depth	number	Maximum recursion depth (0 = infinite, default: 4)
threads	number	Concurrent threads (default: 50)
timeout	number	Request timeout in seconds (default: 7)
rate_limit	number	Max requests per second per directory
filter_status	number[]	Status codes to exclude from results
status_codes	number[]	Status codes to include
filter_size	number[]	Response sizes to exclude
filter_words	number[]	Word counts to exclude
filter_lines	number[]	Line counts to exclude
headers	object	Custom headers (e.g., {"Authorization": "Bearer token"})
proxy	string	Proxy URL (HTTP or SOCKS5)
insecure	boolean	Disable TLS certificate validation
no_recursion	boolean	Disable recursive scanning
force_recursion	boolean	Force recursion on all discovered paths
auto_tune	boolean	Automatically reduce rate on errors
auto_bail	boolean	Automatically stop on excessive errors
silent	boolean	Only output URLs (for piping)
json	boolean	Output results as JSON
background	boolean	Run scan in background
dont_scan	string[]	URLs to exclude from recursion
time_limit	string	Maximum scan time (e.g., "10m", "1h")
scan_limit	number	Maximum concurrent directory scans
user_agent	string	Custom User-Agent string
cookies	string	Cookie string to include
data	string	POST request body
methods	string[]	HTTP methods to use (default: GET)
query	string	Query parameters to append

feroxbuster_config

Configure default settings for subsequent scans. Accepts same filtering and connection parameters as feroxbuster_scan.

feroxbuster_status

Check the status of a running or completed scan.

Parameter	Type	Description
tail_lines	number	Number of output lines to show (default: 50)

feroxbuster_stop

Stop a running scan gracefully. Preserves state file for potential resume.

feroxbuster_resume

Resume a previously interrupted scan from its state file.

Parameter	Type	Description
state_file	string	Path to state file (optional, uses last scan)
background	boolean	Run resumed scan in background

feroxbuster_wordlists

List available wordlists on the remote system.

Parameter	Type	Description
search	string	Filter wordlists by search term
category	string	Category: "common", "directory", "web", "api", "all"

feroxbuster_results

Retrieve and format results from the last completed scan.

Parameter	Type	Description
format	string	Output format: "text", "json", "urls"
filter_status	number[]	Filter results by status codes

feroxbuster_version

Get feroxbuster version information from the remote system.

Usage Examples

Basic Scan

Scan http://target.com for directories and files

Scan with Extensions and Filtering

Scan http://target.com looking for php, html, and txt files.
Exclude 404 and 500 responses. Limit recursion to 3 levels.

Background Scan with Rate Limiting

Start a background scan of http://target.com with rate limiting
at 100 requests/second and auto-tune enabled.

Check Scan Progress

What's the status of my feroxbuster scan?

Resume an Interrupted Scan

Resume the last feroxbuster scan in the background

List Available Wordlists

Show me API-related wordlists on the Kali system

State Management

Scan state is persisted in ~/.feroxbuster-mcp/state.json:

• Active scan information (PID, URL, output file, state file)
• Last scan results for retrieval
• Default configuration settings

This enables scan resumption and result retrieval across sessions.

Security Considerations

• This tool is designed for authorized security testing only
• Always obtain proper authorization before scanning any systems
• Use rate limiting to avoid overwhelming target servers
• Consider using the auto_bail option to stop on errors
• Proxy support enables routing through Burp Suite or other tools

License

MIT License - see LICENSE for details.

Acknowledgments

• feroxbuster by epi052
• Model Context Protocol by Anthropic