# n8n Binary Data Handling

Moves files, images and base64 data correctly through n8n workflows and AI agents.

- Repository: https://github.com/czlonkowski/n8n-mcp (23187 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-27
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add czlonkowski/n8n-mcp --skill n8n-binary-and-data -g -a claude-code -y`
Codex: `npx skills add czlonkowski/n8n-mcp --skill n8n-binary-and-data -g -a codex -y`
Cursor: `npx skills add czlonkowski/n8n-mcp --skill n8n-binary-and-data -g -a cursor -y`
Gemini CLI: `npx skills add czlonkowski/n8n-mcp --skill n8n-binary-and-data -g -a gemini-cli -y`

## Description

Handle files and binary data in n8n correctly. Use when working with files, images, PDFs, attachments, uploads or downloads, base64, vision/multimodal input, or when an AI agent needs a file as tool input or output, and whenever the user mentions $binary, binaryPropertyName, "read the PDF", "attach the file", "send the image", Merge losing binary, or a CDN for chat images. Covers the $binary vs $json split, reading/writing binary, keeping binary alive across transforms with Merge, the agent-tool binary boundary, and the CDN/URL requirement for chat surfaces.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# n8n Binary and Data

Every n8n item carries two independent slots: `$json` for structured data and `$binary` for file bytes. They travel side by side through the workflow. File contents, the actual PDF, image, or zip, live in `$binary`, never in `$json`. Get that split wrong and you read an empty field, lose a file mid-flow, or hand an AI agent a tool input it can't use.

This skill covers where binary lives, how to read and write it, how to keep it from being silently stripped, the hard wall between binary and the AI-agent tool boundary, and why chat surfaces need a URL instead of raw bytes.

---

## The three rules that prevent 90% of binary bugs

1. **File contents are in `$binary`, not `$json`.** After an HTTP download, a "Read Files", or an email-attachment trigger, the bytes sit in `$binary.<key>`. `$json` holds metadata at most. Reading `$json.data` for file contents gives you nothing.

2. **Binary cannot cross the AI-agent tool boundary, in either direction.** Tool arguments and tool return values are JSON only. An uploaded image can't be passed into a tool as a file, and a tool can't return raw bytes. Pre-stage to storage and pass a key or URL through JSON instead. See `AGENT_TOOL_BINARY.md`.

3. **Chat surfaces render images by URL, not by `$binary`.** Slack, Discord, Teams, Telegram, embedded webhook chat, none of them read the binary slot. The image has to live somewhere a URL can fetch it. See `CDN_REQUIREMENT.md`.

---

## The two slots

Each item is shaped like this:

```json
{
  "json": { "customerId": 42, "status": "sent" },
  "binary": {
    "invoice": {
      "data": "<base64-encoded bytes>",
      "mimeType": "application/pdf",
      "fileName": "invoice-42.pdf",
      "fileExtension": "pdf"
    }
  }
}
```

The rest: https://github.com/czlonkowski/n8n-mcp/blob/HEAD/data/skills/n8n-binary-and-data/SKILL.md