Aflpp MCP

🚀 AFL++ MCP Server

The Model Context Protocol (MCP) server for AFL++. This project provides an agent - friendly API to manage various aspects of AFL++ fuzzing workflows.

This repository includes an AFLplusplus checkout. You can initialize it using git submodule update --init with --recursive if you need AFL++ optional mode submodules. The exposed API supports the following operations:

• Creating fuzzing workspaces.
• Instrumenting targets.
• Importing and minimizing corpora.
• Performing harness preflight (dry run / showmap).
• Starting and stopping AFL++ jobs.
• Polling structured status and triaging findings.
• Other related tasks.

🚀 Quick Start

✨ Features

• Agent - friendly API for comprehensive AFL++ fuzzing management.
• Support for various fuzzing - related operations such as workspace creation, target instrumentation, and corpus management.

📦 Installation

Build

npm install
npm run build

Install in Codex CLI

First, build the project. Then, register the MCP server with Codex CLI:

codex mcp add aflpp --env AFLPP_MCP_ROOT="$PWD" -- node "$PWD/dist/index.js"

Run via stdio

node dist/index.js

Environment variables

• AFLPP_MCP_ROOT (default: current working directory)
• AFLPP_DIR (default: $AFLPP_MCP_ROOT/AFLplusplus) – must be inside AFLPP_MCP_ROOT

Other MCP client configs

Claude Desktop

Add the following to your mcpServers config (adjust paths as needed):

{
  "mcpServers": {
    "aflpp": {
      "command": "node",
      "args": ["/home/kevinv/aflpp-mcp/dist/index.js"],
      "env": {
        "AFLPP_MCP_ROOT": "/home/kevinv/aflpp-mcp"
      }
    }
  }
}

💻 Usage Examples

MCP prompts

• aflpp - agent - workflow: High - level end - to - end workflow (build -> corpus -> preflight -> fuzz -> triage).
• aflpp - harness - workplan: Harness - first workflow (usage -> LLVMFuzzerTestOneInput harness -> genesis corpus -> CMPLOG/ASAN/vanilla builds -> launch commands).

MCP resources

• aflpp://config: Server configuration (workspace root, limits, allowlist).
• aflpp://docs/quickstart: Some workflow notes.
• aflpp://docs/fuzzing_in_depth: AFL++'s fuzzing_in_depth.md
• aflpp://docs/cmplog: AFL++'s instrumentation/README.cmplog.md
• aflpp://docs/env_variables: AFL++'s docs/env_variables.md
• aflpp://workspace/{name}/tree: High - level workspace tree
• aflpp://job/{job_name}/latest_status: Latest parsed status snapshot for a job
• aflpp://campaign/{campaign_name}/latest_status: Latest parsed status snapshot for a campaign

MCP tools

• aflpp.list_tools: List AFL++ MCP tools and their short descriptions.
• aflpp.help: Get detailed help for a tool (schema + description).
• aflpp.version: Get AFL++ and server version information.
• aflpp.init_workspace: Create a workspace under workspaces/<name> with standard subdirectories for inputs, outputs, targets, logs, repros, and reports.
• aflpp.detect_build_system: Detect a likely build system for a project path (heuristic).
• aflpp.build_instrumented: Build a target with AFL++ compiler wrappers (and optional sanitizer profiles + build - time knobs) and store the artifact under the workspace targets/ directory.
• aflpp.build_cmplog_variant: Build a CMPLOG - instrumented variant (AFL_LLVM_CMPLOG = 1) and store the artifact under the workspace targets/ directory.
• aflpp.import_corpus: Import a seed corpus from a file or directory into workspaces/<ws>/in/<corpus_name>.
• aflpp.list_corpus: Summarize a corpus directory (file count and total size).
• aflpp.list_builtin_dictionaries: List AFL++ builtin dictionaries shipped in AFLplusplus/dictionaries.
• aflpp.attach_dictionary: Attach a dictionary file to a job name (stored as a job config to be used by aflpp.start_fuzz).
• aflpp.dry_run: Run a short harness validation directly against the target (not afl - fuzz) to check input mode, stability, timeouts, and basic performance.
• aflpp.showmap: Run afl - showmap for a single testcase and return a summary of the trace.
• aflpp.coverage_summary: Measure corpus coverage using afl - showmap -C on an AFL++ output directory (best - effort parsing).
• aflpp.analyze_testcase: Run afl - analyze on a testcase to identify critical input regions.
• aflpp.preflight_checks: Run lightweight preflight checks before starting afl - fuzz (core_pattern, CPU scaling, corpus non - empty).
• aflpp.start_fuzz: Start an afl - fuzz job in the workspace (non - blocking; supports common afl - fuzz knobs + allowlisted env overrides).
• aflpp.start_fuzz_cluster: Start a multi - instance afl - fuzz campaign (master + secondary instances; supports per - instance overrides).
• aflpp.stop_fuzz: Stop a running afl - fuzz job by PID (SIGTERM then SIGKILL).
• aflpp.status: Get job status by parsing fuzzer_stats and queue/crashes/hangs counts (with deltas since last call).
• aflpp.campaign_summary: Summarize a multi - instance campaign by parsing fuzzer_stats for each instance directory.
• aflpp.whatsup: Run afl - whatsup on an AFL++ output directory.
• aflpp.generate_progress_plot: Generate an AFL++ progress plot for a job or campaign (wraps afl - plot).
• aflpp.list_findings: List crash and hang findings with stable IDs and paths.
• aflpp.repro_crash: Reproduce a finding by running the target command directly with the testcase and write a repro bundle under repros/.
• aflpp.crash_report: Write a crash report for a finding (dedup signature + repro info + sanitizer frames if present).
• aflpp.casr_report: Generate clustered crash reports using casr - afl (if installed).
• aflpp.minimize_corpus: Minimize a corpus using afl - cmin and store it as a new corpus directory in the workspace.
• aflpp.minimize_testcase: Minimize a single testcase using afl - tmin and store the minimized testcase under repros/.
• aflpp.suggest_fuzz_cluster_mix: Suggest a multi - core campaign mix (instance_overrides) for aflpp.start_fuzz_cluster.