Cyberchef MCP Server

Pydantic-powered MCP server exposing most CyberChef operations as structured tools.

• Sources for operation metadata: see extract_operations.js
• Operations catalog JSON: utils/js/operations.json

What is this?

This project wraps the CyberChef-server HTTP API in an MCP (Model Context Protocol) server so AI agents and MCP-aware apps can:

• Discover CyberChef operations with fuzzy search
• Inspect the exact argument schema for any operation
• Execute single- or multi-step CyberChef recipes against text or binary data
• Validate and repair recipes programmatically

Prerequisites

You need a running CyberChef-server (the upstream API that performs the actual transforms):

git clone https://github.com/gchq/CyberChef-server
cd CyberChef-server
docker build -t cyberchef-server .
docker run -d --name=cyberchef-server -p 3000:3000 cyberchef-server

By default this MCP server talks to http://localhost:3000/; you can override with --api-url.

Install (local)

# From the project root
python -m venv .venv && source .venv/bin/activate  # or use your preferred env manager
pip install -r requirements.txt

Run (local)

python mcp_cyberchef_service.py \
  --api-url http://localhost:3000/ \
  --host 127.0.0.1 \
  --port 3002

This will start the MCP server using the streamable-http transport on the host/port you provide.

CLI flags:

• --api-url: Base URL of the upstream CyberChef-server (default http://localhost:3000/)
• --host: Interface to bind for the MCP server (default 127.0.0.1)
• --port: Port for the MCP server (default 3002)

Run with Docker

Builds a lightweight image and starts the MCP server on port 3002.

From this directory:

docker build -f Dockerfile -t cyberchef-mcp .

Then run it (pointing to your CyberChef-server):

docker run -d -p 3002:3002 \
  cyberchef-mcp \
  --api-url http://host.docker.internal:3000/ \
  --host 0.0.0.0 \
  --port 3002

MCP Tools exposed

These are the primary tools exported by the MCP server. Argument and return schemas are enforced with Pydantic models.

• search_operations(query: string, limit?: number=10, include_args?: boolean=false) → { total, items[], truncated? } Find relevant CyberChef operations by name/description with fuzzy matching. Optionally include argument lists.
• get_operation_args(op: string, compact?: boolean=true) → { ok, op, args[], error? } Return the exact argument schema for one operation; with compact=true, enum values are slugified.
• bake_recipe(input_data: string, recipe: [{op:string, args?:object}]) → { ok, output?, type?, errors[], warnings[] } Execute a single recipe for one input string.
• batch_bake_recipe(batch_input_data: string[], recipe: [...]) → { results: BakeRecipeResponse[] } Execute the same recipe for many inputs.
• validate_recipe(recipe: [{op, args?}]) → { ok, errors[], suggestions[], normalized? } Validate step names/args and suggest fixes or missing args.
• help_bake_recipe() → Cheat sheet with schema notes and examples for composing recipes.
• cyberchef_probe(raw_input: string) → ProbeOut Quick heuristics to guess encodings and propose a minimal recipe.
• perform_magic_operation(input_data: string, depth?: int=3, intensive_mode?: bool=false, extensive_language_support?: bool=false, crib_str?: string="") → dict Invoke CyberChef Magic; may be slow/approximate.

Tip: Operation names and argument keys are case-sensitive and must match CyberChef exactly. Use search_operations/get_operation_args first.

Example (agent integration)

See example/test-cyberchef.py for a full integration with Microsoft Autogen MCP workbench. It spins up this server and drives it strictly via tools. A minimal flow:

1. search_operations("base64") to shortlist "From Base64".
2. bake_recipe with:
   • input_data: "SGVsbG8gV29ybGQh"
   • recipe: [{"op":"From Base64","args":{}}]

Cross platform builds

Only once: docker buildx create --use --name xbuilder

Further updates:

docker buildx use xbuilder
docker buildx build --platform linux/amd64 -f mcp_servers/mcp_cyberchef/Dockerfile -t cyberchef-mcp-amd64 --load .
docker buildx use default

Troubleshooting

• Connection errors when baking recipes: ensure CyberChef-server is running and --api-url points to it.
• Unknown op / bad args: call get_operation_args(op) and confirm exact key names and allowed enum values.
• Large search results: lower limit or narrow your query; the server truncates responses to stay under size caps.