CyberChef MCP Server

This project provides a Model Context Protocol (MCP) server interface for CyberChef, the "Cyber Swiss Army Knife" created by GCHQ.

By running this server, you enable AI assistants (like Claude, Cursor AI, and others) to natively utilize CyberChef's extensive library of 504 data manipulation operations—including encryption, encoding, compression, and forensic analysis—as executable tools.

Latest Release: v4.2.0 | Release Notes | Tutorial | Examples | Breaking Changes | Security Policy

Upstream base: GCHQ CyberChef v11.4.0 | Licence: GPL-3.0-or-later (from v2.0.0; v1.9.x and earlier remain Apache-2.0)

Project Context

CyberChef is a simple, intuitive web app for carrying out all manner of "cyber" operations within a web browser. It was originally conceived and built by GCHQ.

This fork wraps the core CyberChef Node.js API into an MCP server, bridging the gap between natural language AI intent and deterministic data processing.

Fork Relationship

This project maintains a selective sync relationship with the upstream GCHQ/CyberChef repository:

• Synced from upstream: src/core/** (minus three generated paths) and six upstream-owned files in src/node/. Mirrored verbatim — never hand-edit them; fork changes live as re-applied patches.
• Web UI Components: Removed (88 files, ~19,260 lines) — not needed for an MCP server
• MCP-Specific Code: this fork's own (src/node/mcp-server.mjs, src/node/lib/**, tests/mcp/, workflows)
• Sync is one-way: pull only. As of v2.0.0 the combined work is GPL-3.0-or-later, so MCP-layer changes cannot be contributed back to an Apache-2.0 upstream.

Exact scope, the patch model, and what to do when a sync conflicts: Upstream Sync Guide.

See Upstream Sync Guide for details on the synchronization process.

Features

MCP Tools

The server exposes CyberChef operations as MCP tools:

• Runs on ARM, and 30% smaller (v2.8.0): images are published for linux/arm64 as well as linux/amd64 — Apple Silicon, Graviton, Raspberry Pi 4/5 — and the image is down from 643 MB to 453 MB. Also CYBERCHEF_OFFLINE=true for air-gapped hosts: 502 of the 504 operations never touched a network anyway, so this is a fail-closed switch for the two that do, checked against the recipe rather than the tool name. See the edge deployment guide for architectures, sizing and air-gapped install, and the release notes for how the size reduction was done and verified.
• Observable (v2.7.0): a dependency-free Prometheus endpoint at /metrics (20 metric families, off by default — unlike the health probes it reports which tools are used, how often and how large the inputs are, which is a reconnaissance surface), OpenTelemetry spans following the MCP semantic conventions, and trace_id/span_id on every log line. It adds one package: the OTel API, not the SDK — measured at 1 package / 2.6 MB / +9 ms against the SDK's 71 packages / 50 MB / +100 ms, which would have handed back more than half of v2.6.0's startup work on every stdio launch. You supply the SDK, so every OTLP backend works rather than a chosen few. Ships a Grafana dashboard, alert rules and a runnable Prometheus stack — all executed against a live server rather than reviewed. Tool arguments are never recorded: the conventions mark them Opt-In, and for this server the arguments are the sensitive material.
• OAuth 2.1 authentication on HTTP (v2.5.0): the server acts as an OAuth 2.1 Resource Server — RFC 9728 Protected Resource Metadata, JWKS-based bearer validation, and RFC 8707 audience binding, which is the check that stops a token minted for another service being replayed here. Scope-based RBAC with three scopes (cyberchef:read, cyberchef:write, cyberchef:network), where the scope a tool needs is derived from its annotations rather than a table that goes stale. Audit logging for who called what. Off unless CYBERCHEF_AUTH_ISSUER is set, and deliberately not applied to stdio — the MCP specification says stdio SHOULD NOT use OAuth, because a bearer token protects nothing when the client already owns the process.
• Multi-tenancy (v2.5.0): the operation cache, recipe store, concurrency pool and audit trail are isolated per tenant, with the tenant read from a claim on an already-verified token (CYBERCHEF_TENANT_CLAIM) — never from a header the caller controls. Without it, any caller on a shared HTTP deployment could list, modify and delete any other caller's saved recipes, and clear() destroyed every tenant's at once. Off unless configured, and configuring it without CYBERCHEF_AUTH_ISSUER is a startup error rather than a silent downgrade.
• Starts in ~185 ms (v2.6.0): it used to take ~1.3 seconds, of which ~1.15 s was importing all 504 operation implementations before answering anything — paid on every launch, on stdio, which is how every editor starts the server. The 504-operation barrel is now loaded only by the three tools that need it (cyberchef_search, batch search, and saved-recipe execution). tools/list is built from metadata, and an ordinary operation call loads just the one operation it runs — verified: cyberchef_bake completes without the barrel being loaded at all. A background warm-up was tried, measured, and removed: module loading blocks the event loop, so it just moved the cost in front of the first request.
• Deployable as a service (v2.6.0): a Helm chart and Compose file with liveness/readiness/startup probes and a drain that loses no requests during a rolling update. Liveness deliberately stays healthy while draining — a liveness failure there gets the pod killed mid-drain. The chart refuses to render configurations the server would reject at startup, so they fail at helm template rather than as a crashloop.
• Bounded calls to the authorization server (v2.6.0): JWKS discovery had no timeout (Node's fetch has none by default) and cached failures not at all, so an issuer outage turned every request into two outbound ones that could hang until the OS gave up. Now a 5 s deadline and a circuit breaker: 20 verifications against a down issuer went from 40 outbound attempts to 10.
• Nineteen analysis tools that are not operations (v2.4.0, expanded through v3.11.0): the original four are cyberchef_xor_key_length (repeating-key XOR length by index of coincidence), cyberchef_cyclic_pattern (De Bruijn patterns and overflow offsets, byte-compatible with pwntools' cyclic), cyberchef_hash_identify (hash format with the hashcat mode and John format name) and cyberchef_rsa_attack (Fermat, shared factors, Wiener and unpadded small-e). Twelve more arrived in v3.3.0 (classical ciphers, crib dragging, entropy scanning, hash cracking and statistics, JWT weaknesses, plaintext scoring, multi-key RSA, substitution and Vigenère breaking, timestamp identification, corpus diffing), then cyberchef_ecdsa_recover in v3.4.0 (private-key recovery from a reused ECDSA nonce) and cyberchef_cert_chain in v3.8.0 (orders an X.509 bundle, verifies every link cryptographically, and reports the chain's validity window as the intersection of its members', both ends). cyberchef_pqc_identify arrived in v3.11.0: it names the NIST post-quantum parameter set behind a key, signature or ciphertext — ML-KEM (FIPS 203), ML-DSA (FIPS 204) or SLH-DSA (FIPS 205) — from the OID when there is DER to read, and from byte length when there is not, in which case it reports every candidate and says so rather than picking one. See Analysis Tools. An operation is a pure run(input, args) over one input and cannot express an analysis; cyberchef_bake cannot either, because a recipe is a pipeline, not a loop. Since v4.1.0 they are reached through cyberchef_analyse({tool, arguments}) on the default index surface, and remain listed outright on curated and all — nineteen of them had been 68% of the index, listed only because cyberchef_describe_operation refused them and pointed at tools/list, which made the listing their sole schema path. There is deliberately no plugin loader — node:vm is not a security boundary, and that was measured rather than assumed (ADR 0002).
• Protocol revision 2026-07-28 (v2.3.0): served on both stdio and HTTP alongside the 2025 era, from one set of handlers. Existing clients are unaffected — a v1-SDK client still negotiates 2025-11-25 against the same registrations. On HTTP the two eras are routed per request by the SDK's own classifier, so 2025 traffic keeps the sessionful wiring while modern traffic is served per request.
• Three transports (v2.3.0): stdio, Streamable HTTP, and a socket binding over a Unix domain socket or loopback TCP (CYBERCHEF_TRANSPORT=socket), one pinned server instance per connection. It carries no authentication, so a non-loopback bind is refused unless explicitly allowed and the Unix socket is created 0600. There is deliberately no WebSocket transport — MCP does not define one.
• Every image operation works (v2.3.0): 17 of them returned Node's shared buffer pool instead of the image — unreadable output, and the surplus was whatever the process had recently allocated. Add Text To Image had never worked in this fork at all, since v1.7.1. Both are fixed as fork patches.
• Images and audio come back as images and audio (v2.2.0): Generate QR Code, Render Image and the image set return an MCP image content block; Play Media returns an audio block. Before v2.2.0 the html-to-text conversion deleted the payload and these operations returned an empty string — they had never worked over MCP. Other binary stays byte-lossless latin1 text, or base64 with CYBERCHEF_BINARY_OUTPUT=base64.
• Tool annotations on every tool (v2.2.0): readOnlyHint, destructiveHint, idempotentHint, openWorldHint and a readable title, so a client can skip the approval prompt for a pure operation. The exceptions were measured, not guessed — only HTTP request and DNS over HTTPS reach the network, and non-idempotence was determined by running each candidate twice and comparing.
• Prompts and resources (v2.2.0): five workflow prompts (analyse-unknown-data, extract-iocs, deobfuscate-script, identify-hash, decode-chain) for when you do not yet know which of 504 operations you need, and saved recipes exposed as readable resources at recipe://<id>.
• cyberchef_bake: The "Omni-tool". Executes a full CyberChef recipe (a chain of operations) on an input. Ideal for complex, multi-step transformations (e.g., "Decode Base64, then Gunzip, then prettify JSON").
• All 504 operations, without paying for 504 schemas (v2.1.0): tools/list is an index by default — 23 tools and 15,620 bytes, rather than 545 tools and 426,706 bytes. Every operation stays reachable: cyberchef_categories -> cyberchef_list_operations -> cyberchef_describe_operation walks down to any of them, cyberchef_search finds one by keyword, and cyberchef_bake runs any of them by name. The 19 analysis tools are reachable the same way, through cyberchef_describe_operation and cyberchef_analyse — they were listed on every surface until v4.1.0, where nineteen of them were 68% of the index, because describe_operation used to refuse them and point at tools/list, making the listing their only schema path. CYBERCHEF_TOOL_SURFACE=curated (120 tools, 109,548 bytes) or =all (all 545, 426,706 bytes) if you would rather pre-load; both still list every analysis tool outright. See the User Guide.
  • cyberchef_to_base64 / cyberchef_from_base64
  • cyberchef_aes_decrypt
  • cyberchef_sha2
  • cyberchef_yara_rules
  • ...and hundreds more.
• cyberchef_search: A utility tool to help the AI discover available operations and their descriptions.
• Recipe Management (v1.6.0): 10 tools for saving, organizing, and reusing multi-operation workflows
  • cyberchef_recipe_create / cyberchef_recipe_get / cyberchef_recipe_list
  • cyberchef_recipe_update / cyberchef_recipe_delete / cyberchef_recipe_execute
  • cyberchef_recipe_export / cyberchef_recipe_import
  • cyberchef_recipe_validate / cyberchef_recipe_test
• Advanced Features (v1.7.0): 5 new tools for enterprise-grade capabilities
  • cyberchef_batch - Execute multiple operations in parallel or sequential mode
  • cyberchef_telemetry_export - Privacy-first usage analytics (opt-in)
  • cyberchef_cache_stats / cyberchef_cache_clear - Cache inspection and management
  • cyberchef_quota_info - Resource quota and usage tracking
• Migration tooling — REMOVED in v4.0.0. cyberchef_migration_preview, cyberchef_deprecation_stats and the cyberchef-migrate binary existed to help callers reach v2.0.0, nine minors earlier. They were advertised on every surface and cost 995 bytes of every tools/list, while the only warning still emitted was DEP007 — a withdrawn code whose own text read "No action required". Your v1-format recipes need no migration: positional arguments, bare string operations and named-object arguments all bake identically today.
  • The cyberchef_ prefix is permanent. DEP001, DEP007 and DEP008 announced its removal in v1.8.0 and were withdrawn in v2.0.0: removing it saves 2.6% of the tools/list payload while colliding 19 tool names in MCP's flat namespace and breaking every existing integration. Keep using cyberchef_to_base64, cyberchef_bake and cyberchef_search. See v2.0.0 Breaking Changes.
• Worker Thread Pool (v1.9.0): CPU-intensive operations offloaded to worker threads
  • cyberchef_worker_stats - Monitor worker pool utilization, active/completed tasks, and pool configuration
  • Enable with CYBERCHEF_ENABLE_WORKERS=true environment variable
  • Configurable pool size, idle timeout, and minimum input size for worker routing

Technical Highlights

• Dockerized: Runs as a self-contained Docker container on a Chainguard Wolfi Node.js base (v26.8.1 at time of writing), pinned by digest and bumped weekly by Dependabot. Measured against the published v3.1.0 image: 453 MB on disk, 141 MB as the gzipped release tarball, running as UID 65532 (nonroot). The base is rebuilt daily and carries no package manager (apk, wget and curl are all absent) -- but it does include a BusyBox shell and npm, so treat a container compromise as having a shell available. This line previously claimed "no shell" and "726 MB on disk"; both were wrong, and the correction is recorded in the v3.1.0 baseline.
• Dual-Registry Publishing: Images published to both Docker Hub and GitHub Container Registry (GHCR) for maximum accessibility and Docker Scout health score optimization.
• Supply Chain Attestations: SBOM and provenance attestations attached to Docker Hub images for enhanced security transparency and compliance (SLSA Build Level 3).
• Dual Transport (v1.9.0; per-session HTTP since v2.0.0): Stdio (default) or Streamable HTTP via CYBERCHEF_TRANSPORT=http. Every HTTP client gets its own session and its own MCP server instance, with CORS, DNS-rebinding protection and a session cap. See the HTTP Transport Guide.
• MCP Streaming with Progress (v1.9.0): Operations send notifications/progress via the MCP SDK progress token mechanism for real-time status updates during long-running tasks.
• Worker Thread Pool (v1.9.0): Piscina-based worker threads offload CPU-intensive operations (AES, Blowfish, bcrypt, scrypt, PBKDF2, etc.) to prevent event loop blocking. Configurable pool size and routing thresholds.
• Schema Validation: All inputs are validated against schemas derived from CyberChef's internal type system using zod.
• Modern Node.js: Requires Node.js >=26 <27 since v4.0.0, and the published image runs Node 26 -- floor and runtime are now the same version rather than two majors apart.
• Recipe Management (v1.6.0): Save and reuse multi-operation workflows with full CRUD operations, import/export in multiple formats (JSON/YAML/URL/CyberChef), recipe composition with nesting support, and curated library of 25+ production-ready recipes across 5 categories. See Recipe Management Guide for details.
• Advanced Features (v1.7.0): Enterprise-grade capabilities with batch processing (parallel/sequential execution of up to 100 operations), privacy-first telemetry collection (disabled by default, no input/output data captured), sliding window rate limiting for resource protection, enhanced caching with inspection tools, and resource quota tracking (concurrent operations, data sizes). All features are configurable via environment variables with secure defaults. See Release Notes for details.
• Enhanced Observability (v1.5.0): Structured JSON logging with Pino for production monitoring, comprehensive error handling with actionable recovery suggestions, automatic retry logic with exponential backoff, request correlation with UUID tracking, circuit breaker pattern for cascading failure prevention, and streaming infrastructure for progressive results on large operations. See Release Notes for details.
• Performance Optimized (v1.4.0): LRU cache for operation results (100MB default), automatic streaming for large inputs (10MB+ threshold), configurable resource limits (100MB max input, 30s timeout), memory monitoring, and comprehensive benchmark suite. See Performance Tuning Guide for configuration options.
• Upstream Sync Automation (v1.3.0; rebuilt in v2.0.0): Weekly monitoring of upstream releases, an atomic whole-tree mirror, fork changes carried as patches that fail the sync if they stop applying, comprehensive validation (1,246 MCP + 241 Node-API + 2,289 operation tests), and an emergency rollback. See the Upstream Sync Guide.
• Security Hardened (v1.4.5+): Chainguard Wolfi base image with zero-CVE baseline, non-root execution (UID 65532), automated Trivy vulnerability scanning with build-fail thresholds, dual SBOM strategy (Docker Scout attestations + CycloneDX), read-only filesystem support, SLSA Build Level 3 provenance, and 7-day SLA for critical CVE patches. Fixed 11 of 12 code scanning vulnerabilities including critical cryptographic randomness weakness and 7 ReDoS vulnerabilities. See Security Policy and Security Fixes Report for details.
• Production Ready: Comprehensive CI/CD with CodeQL v4, automated testing, and dual-registry container publishing (Docker Hub + GHCR) with complete supply chain attestations.

Quick Start

Prerequisites

• Node.js >=26 <27 for the npm install, or Docker for the container.

Installation Options

Option 1: npm (Recommended)

npx cyberchef-mcp

No clone, no build, no Docker daemon. For an MCP client, point it at the same command:

{
  "mcpServers": {
    "cyberchef": { "command": "npx", "args": ["-y", "cyberchef-mcp"] }
  }
}

Installing it permanently works too — npm install -g cyberchef-mcp, then run cyberchef-mcp. That is the only binary the package ships; cyberchef-migrate was removed in v4.0.0.

Option 2: Pull from Docker Hub

# Docker Hub provides health scores and supply chain attestations
docker pull parobek/cyberchef-mcp:latest
docker tag parobek/cyberchef-mcp:latest cyberchef-mcp
docker run -i --rm cyberchef-mcp

Option 2b: Pull from GitHub Container Registry (Alternative)

docker pull ghcr.io/doublegate/cyberchef-mcp_v4:latest
docker tag ghcr.io/doublegate/cyberchef-mcp_v4:latest cyberchef-mcp
docker run -i --rm cyberchef-mcp

Option 3: Download Pre-built Image (Offline Installation)

For environments without direct GHCR access, download the pre-built Docker image tarball from the latest release:

1. Download the tarball (141 MB compressed; measured against the published v3.1.0 asset, not estimated):

   # Download from GitHub Releases
   wget https://github.com/doublegate/CyberChef-MCP/releases/download/v4.2.0/cyberchef-mcp-v4.2.0-docker-image.tar.gz
   

2. Load the image into Docker:

   docker load < cyberchef-mcp-v4.2.0-docker-image.tar.gz
   

3. Tag for easier usage:

   docker tag parobek/cyberchef-mcp:latest cyberchef-mcp
   

4. Run the server:

   docker run -i --rm cyberchef-mcp
   

Option 4: Build from Source

1. Clone the Repository:

   git clone https://github.com/doublegate/CyberChef-MCP.git
   cd CyberChef-MCP
   

2. Build the Docker Image:

   docker build -f Dockerfile.mcp -t cyberchef-mcp .
   

3. Run the Server (Interactive Mode): This command starts the server and listens on stdin. This is what your MCP client will run.

   docker run -i --rm cyberchef-mcp
   

4. Optional: Run with Enhanced Security (Read-Only Filesystem): For maximum security in production deployments:

   docker run -i --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=100m cyberchef-mcp
   

Client Configuration

Cursor AI

1. Go to Settings > Features > MCP.
2. Add a new server:
   • Name: CyberChef
   • Type: command
   • Command: docker
   • Args: run -i --rm cyberchef-mcp

Claude Code (CLI)

Add to your configuration file (typically ~/.config/claude/config.json):

{
  "mcpServers": {
    "cyberchef": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "cyberchef-mcp"]
    }
  }
}