# cyberchef-mcp-server

An MCP (Model Context Protocol) server that exposes [CyberChef](https://github.com/gchq/CyberChef)'s
~480 data operations — encoding/decoding, hashing, compression, encryption, data format
conversion, and more — as tools an LLM agent can call directly, via CyberChef's
[Node.js API](https://github.com/gchq/CyberChef/wiki/Node-API).

## Tools

| Tool | Purpose |
| --- | --- |
| `cyberchef_bake` | Run a CyberChef "recipe" (one or more chained operations) against input data. |
| `cyberchef_list_operations` | Search CyberChef's operation catalog by name, category, or description. |
| `cyberchef_operation_help` | Get an operation's description, input/output types, and argument names/defaults. |

Typical flow for an agent: `cyberchef_list_operations` (find the op) →
`cyberchef_operation_help` (confirm its arguments) → `cyberchef_bake` (run it).

Note: CyberChef's Magic operation (auto-detecting unknown encodings) is a flow-control
operation, and the Node API explicitly rejects flow-control operations in `bake()` — so it
can't be exposed as a tool here, only the browser UI supports it.

## Setup

```bash
npm install
npm run setup
npm run build
```

`npm run setup` is required, not optional — see "Why `npm run setup`?" below.

## Running standalone

```bash
npm start
```

The server communicates over stdio, per MCP convention — it isn't a long-running HTTP
service and won't print anything on stdout itself.

## Registering with an MCP client

Add an entry to your client's MCP server config, pointing at the built entry point, e.g.
for Claude Code / Claude Desktop:

```json
{
  "mcpServers": {
    "cyberchef": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-cyberchef/dist/index.js"]
    }
  }
}
```

## Development

```bash
npm run dev         # run src/index.ts directly with tsx, restarting on change
npm test            # run the unit tests (node:test via tsx)
npm run build       # type-check and compile to dist/
npm run smoke-test  # spawn the built server and drive it with a real MCP client
```

## Why `npm run setup`?

`cyberchef@11.2.0`'s own `postinstall` script (`npx grunt exec:fixCryptoApiImports && ...`)
requires `grunt`/`grunt-exec`/`grunt-webpack`/etc., which only exist in *cyberchef's own*
devDependencies — npm never installs those for a consumer, so that postinstall always
crashes a fresh `npm install`. `.npmrc` sets `ignore-scripts=true` project-wide so install
can complete at all (this also skips harmless postinstalls, like `esbuild`'s and
`tesseract.js`'s funding message).

`npm run setup` replaces the one fixup that actually matters for us:
[`fixCryptoApiImports`](scripts/fix-crypto-api-imports.mjs) appends `.mjs` extensions to
`node_modules/crypto-api`'s relative imports, which Node's strict ESM resolver requires but
crypto-api's published source omits — without it, every hash operation throws
`ERR_MODULE_NOT_FOUND`. It also runs `esbuild`'s install step by hand, since that's needed
for `tsx` (used by `npm run dev`/`test`) and would otherwise be skipped along with everything
else.

Two more of cyberchef's dependencies are simply missing from its published `package.json`
(`yaml`, used by `JSONtoYAML`; `js-yaml`, used by `YAMLToJSON`) — those are just declared as
direct dependencies here instead. `js-yaml` is pinned to `^4` deliberately: v5 dropped the
default export cyberchef's source imports.