AFL++ MCP server

Model Context Protocol (MCP) server for AFL++.

This repo includes an AFLplusplus checkout (git submodule update --init with --recursive if you need AFL++ optional mode submodules) and exposes an agent-friendly API for:

• creating fuzzing workspaces,

• instrumenting targets,

• corpus import/minimization,

• harness preflight (dry run / showmap),

• starting/stopping AFL++ jobs,

• polling structured status and triaging findings,

• other stuff

Install

Build

npm install
npm run build

Install in Codex CLI

Build first, 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 to your mcpServers config (adjust paths):

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

Related MCP server: Azure AI Foundry MCP Server

How to use

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.