proxy-mcp

Instructions

Implementation Reference

• src/tools/tls.ts:145-221 (handler)

  The 'proxy_set_fingerprint_spoof' tool handler, which processes input parameters to configure browser presets and fingerprint overrides, then invokes 'proxyManager.setFingerprintSpoof' to apply the spoofing configuration.

  server.tool(
    "proxy_set_fingerprint_spoof",
    "Enable outgoing TLS + HTTP/2 fingerprint spoofing via curl-impersonate (requires Docker or Podman). Supports browser presets that select a curl-impersonate target binary (BoringSSL + nghttp2, matching real Chrome/Firefox). Individual parameters override preset values.",
    {
      preset: z.string().optional().describe("Browser preset name (e.g. 'chrome_131', 'chrome_136'). Use proxy_list_fingerprint_presets to see available options. Individual params below override preset values."),
      ja3: z.string().optional().describe("JA3 fingerprint string. Required if no preset is given."),
      user_agent: z.string().optional().describe("User-Agent header to use with spoofed requests"),
      host_patterns: z.array(z.string()).optional().describe("Only spoof requests to hostnames containing these substrings. Empty = spoof all HTTPS."),
      http2_fingerprint: z.string().optional().describe("HTTP/2 fingerprint (SETTINGS|WINDOW_UPDATE|PRIORITY frames). E.g. '1:65536;2:0;3:1000;4:6291456;6:262144|15663105|0:1:256:0,...'"),
      header_order: z.array(z.string()).optional().describe("Header order for outgoing requests (e.g. ['host','user-agent','accept',...])"),
      order_as_provided: z.boolean().optional().describe("Send headers in the exact order provided (default: true when header_order is set)"),
      disable_grease: z.boolean().optional().describe("Disable GREASE values in TLS ClientHello"),
      disable_redirect: z.boolean().optional().describe("Disable automatic redirect following"),
      force_http1: z.boolean().optional().describe("Force HTTP/1.1 instead of HTTP/2"),
      insecure_skip_verify: z.boolean().optional().describe("Skip TLS certificate verification"),
    },
    async ({ preset, ja3, user_agent, host_patterns, http2_fingerprint, header_order, order_as_provided, disable_grease, disable_redirect, force_http1, insecure_skip_verify }) => {
      try {
        // Resolve preset as base, then apply explicit overrides
        let config: FingerprintSpoofConfig;
  
        if (preset) {
          const base = resolveBrowserPreset(preset);
          config = {
            ja3: ja3 ?? base.ja3,
            userAgent: user_agent ?? base.userAgent,
            hostPatterns: host_patterns,
            http2Fingerprint: http2_fingerprint ?? base.http2Fingerprint,
            headerOrder: header_order ?? base.headerOrder,
            orderAsProvided: order_as_provided ?? base.orderAsProvided,
            disableGrease: disable_grease,
            disableRedirect: disable_redirect,
            forceHTTP1: force_http1,
            insecureSkipVerify: insecure_skip_verify,
            preset,
          };
        } else {
          if (!ja3) {
            return { content: [{ type: "text" as const, text: JSON.stringify({ status: "error", error: "Either 'preset' or 'ja3' is required" }) }] };
          }
          config = {
            ja3,
            userAgent: user_agent,
            hostPatterns: host_patterns,
            http2Fingerprint: http2_fingerprint,
            headerOrder: header_order,
            orderAsProvided: order_as_provided ?? (header_order ? true : undefined),
            disableGrease: disable_grease,
            disableRedirect: disable_redirect,
            forceHTTP1: force_http1,
            insecureSkipVerify: insecure_skip_verify,
          };
        }
  
        await proxyManager.setFingerprintSpoof(config);
  
        const warnings: string[] = [];
        if (!preset && ja3) {
          warnings.push("Custom JA3 strings are not supported by the curl-impersonate backend. The default Chrome preset fingerprint will be used. Use a preset for explicit control.");
        }
  
        return {
          content: [{
            type: "text" as const,
            text: JSON.stringify({
              status: "success",
              message: "Fingerprint spoofing enabled",
              ...(warnings.length > 0 ? { warnings } : {}),
              config,
            }),
          }],
        };
      } catch (e) {
        return { content: [{ type: "text" as const, text: JSON.stringify({ status: "error", error: String(e) }) }] };
      }
    },
  );

• src/tools/tls.ts:146-146 (registration)

  Registration of the 'proxy_set_fingerprint_spoof' tool within the server.

  "proxy_set_fingerprint_spoof",