nuclei-server MCP Server

Instructions

Implementation Reference

• src/index.ts:112-218 (handler)

  Executes the start_scan tool: checks concurrent scan limit, parses arguments, creates scan ID and entry, builds nuclei command line with options, spawns process, streams stdout for progress, parses JSON findings on close, handles errors.

  if (request.params.name === "start_scan") {
    const activeScans = Object.values(scans).filter(
      (scan) => scan.status === "running"
    ).length;
    if (activeScans >= MAX_CONCURRENT_SCANS) {
      return {
        content: [
          {
            type: "text",
            text: `Reached maximum concurrent scans (${MAX_CONCURRENT_SCANS}), please try again later`,
          },
        ],
        isError: true,
      };
    }
  
    const { target, template, rateLimit, templatesDir, severity, timeout, concurrency, proxyUrl, proxyType } =
      request.params.arguments as {
        target: string;
        template?: string;
        rateLimit?: number;
        templatesDir?: string;
        severity?: string;
        timeout?: number;
        concurrency?: number;
        proxyUrl?: string;
        proxyType?: string;
      };
  
    const scanId = uuidv4();
    scans[scanId] = {
      id: scanId,
      target,
      status: "pending",
      progress: 0,
      findings: [],
    };
  
    let command = `nuclei -u ${target} ${severity ? `-severity ${severity}` : ""} ${
      template ? `-t ${template}` : ""
    } ${rateLimit ? `-rl ${rateLimit}` : ""} ${templatesDir ? `-templates ${templatesDir}` : ""} ${
      timeout ? `-timeout ${timeout}` : ""
    } ${concurrency ? `-c ${concurrency}` : ""} -json`;
  
    if (proxyUrl && proxyType) {
      if (proxyType === "socks5") {
        command += ` -proxy-socks-url ${proxyUrl}`;
      } else {
        command += ` -proxy-url ${proxyUrl}`;
      }
    }
  
    try {
      scans[scanId].status = "running";
  
      const process = spawn(command, {
        shell: true,
        stdio: ["pipe", "pipe", "pipe"],
      });
  
      let output = "";
      process.stdout.on("data", (data) => {
        output += data.toString();
        scans[scanId].progress = Math.min(100, Math.round((output.split("\n").length / 100) * 100));
      });
  
      process.on("close", () => {
        scans[scanId].progress = 100;
        const findings = output
          .split("\n")
          .filter(Boolean)
          .map((line) => {
            try {
              return JSON.parse(line);
            } catch {
              return null;
            }
          })
          .filter(Boolean);
  
        scans[scanId].findings = findings;
        scans[scanId].status = "completed";
      });
  
      scans[scanId].process = process;
  
      return {
        content: [
          {
            type: "text",
            text: `Scan ${scanId} started`,
          },
        ],
      };
    } catch (error) {
      scans[scanId].status = "failed";
      return {
        content: [
          {
            type: "text",
            text: `Scan ${scanId} failed: ${error instanceof Error ? error.message : "Unknown error"}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:72-95 (schema)

  Defines the input schema and parameters for the start_scan tool.

    name: "start_scan",
    description: "Start a new nuclei scan",
    inputSchema: {
      type: "object",
      properties: {
        target: { type: "string", description: "Target URL or IP address" },
        template: { type: "string", description: "Template to use for scanning" },
        rateLimit: { type: "number", description: "Rate limit per second" },
        templatesDir: { type: "string", description: "Directory with templates" },
        severity: { type: "string", enum: ["info", "low", "medium", "high", "critical"] },
        timeout: { type: "number", description: "Timeout in seconds" },
        concurrency: { type: "number", description: "Concurrent requests" },
        proxyUrl: {
          type: "string",
          description: "Proxy URL (e.g., socks5://127.0.0.1:1080)"
        },
        proxyType: {
          type: "string",
          enum: ["http", "socks5"]
        },
      },
      required: ["target"],
    },
  },

• src/index.ts:68-109 (registration)

  Registers the start_scan tool by listing it in the tools response.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "start_scan",
          description: "Start a new nuclei scan",
          inputSchema: {
            type: "object",
            properties: {
              target: { type: "string", description: "Target URL or IP address" },
              template: { type: "string", description: "Template to use for scanning" },
              rateLimit: { type: "number", description: "Rate limit per second" },
              templatesDir: { type: "string", description: "Directory with templates" },
              severity: { type: "string", enum: ["info", "low", "medium", "high", "critical"] },
              timeout: { type: "number", description: "Timeout in seconds" },
              concurrency: { type: "number", description: "Concurrent requests" },
              proxyUrl: {
                type: "string",
                description: "Proxy URL (e.g., socks5://127.0.0.1:1080)"
              },
              proxyType: {
                type: "string",
                enum: ["http", "socks5"]
              },
            },
            required: ["target"],
          },
        },
        {
          name: "cancel_scan",
          description: "Cancel a running scan",
          inputSchema: {
            type: "object",
            properties: {
              scanId: { type: "string", description: "Scan ID to cancel" },
            },
            required: ["scanId"],
          },
        },
      ],
    };
  });

• src/index.ts:14-21 (helper)

  Type definition for scan results used by start_scan handler.

  interface ScanResult {
    id: string;
    target: string;
    progress: number;
    status: "pending" | "running" | "completed" | "failed" | "canceled";
    findings: any[];
    process?: any;
  }