TokenCalculator for n8n

Add a local preflight step before an LLM call. The node can count mapped text, combine multiple text or source files, apply provider image-token formulas, estimate cost, and compare models without sending the input to TokenCalculator.dev.

What is an n8n token calculator?

An n8n token calculator is a workflow step that measures an LLM request before the paid model call. TokenCalculator turns prompts, form uploads, source files, and images into an input-token count, context-window usage, and model cost estimate. It fits AI agents, document-processing forms, support automation, content pipelines, and any n8n workflow that needs a predictable token or spending limit.

Install the community node

1. In n8n, open Settings → Community nodes.
2. Select Install and enter @jay0073/n8n-nodes-tokencalculator.
3. Accept n8n's community-node notice, install the package, then search the node picker for Token Calculator.

Use version 0.1.5 or later for multiple-file Form Trigger support. If your deployment manages community packages through environment variables, the UI cannot remove or update them; change the deployment configuration and restart n8n instead.

Quick start: dynamic text

1. Add a Manual Trigger, then an Edit Fields or Code node that outputs a field named text.
2. Add Token Calculator and choose Count Tokens.
3. Set Input Source to Text.
4. Set Text to {{ $json.text }}, choose a model, and execute the step.

The expression must resolve to a real field in the incoming item. If the input panel shows undefined, inspect the previous node's JSON and drag the correct field into Text.

Importable starter workflow

Copy this JSON, choose Import from clipboard in n8n, and run it. The community node must already be installed.

{
  "name": "TokenCalculator preflight",
  "nodes": [
    { "parameters": {}, "id": "manual-trigger", "name": "Run workflow", "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [240, 300] },
    { "parameters": { "jsCode": "return [{ json: { text: 'Summarize this customer message in three bullets.' } }];" }, "id": "sample-text", "name": "Sample text", "type": "n8n-nodes-base.code", "typeVersion": 2, "position": [460, 300] },
    { "parameters": { "operation": "count", "source": "text", "text": "={{ $json.text }}", "modelId": "gpt-5.6-terra" }, "id": "token-calculator", "name": "Token Calculator", "type": "@jay0073/n8n-nodes-tokencalculator.tokenCalculator", "typeVersion": 1, "position": [700, 300] }
  ],
  "connections": {
    "Run workflow": { "main": [[{ "node": "Sample text", "type": "main", "index": 0 }]] },
    "Sample text": { "main": [[{ "node": "Token Calculator", "type": "main", "index": 0 }]] }
  },
  "settings": {}
}

Choose the right input mode

• Text: mapped prompts, messages, database fields, webhook bodies, or text assembled by an earlier Code node.
• Binary File: one or more incoming text/source/data files or supported images.
• Text and Binary File: combines mapped text with every selected binary file into one measurement.

Readable text formats include TXT, Markdown, JSON, CSV, common source-code formats, HTML/XML, YAML, SQL, shell scripts, and logs. Images include PNG, JPEG, GIF, and WebP. Each file is limited to 10 MB. PDF and DOCX extraction is not performed by this node; extract their text in an earlier node and map the result through Text.

Form Trigger and multiple files

n8n stores Form Trigger uploads as binary properties. A multi-file field commonly becomes several properties with numeric suffixes. Token Calculator supports all of them:

1. In Form Trigger, add a File field and enable multiple-file upload.
2. Connect it directly to Token Calculator.
3. Choose Binary File or Text and Binary File.
4. Set Binary Properties to * for every incoming file. Use uploads* for properties beginning with uploads, or a comma-separated list such as contract0,contract1.

All readable text files are joined with blank lines. Every supported image contributes its own token allocation. The output's source.files array records each filename, size, extraction method, and n8n binary property.

Useful workflow recipes

Reject an oversized prompt before the LLM

Send the false branch to the LLM. Route the true branch to a chunking step, storage, or a clear error response.

Apply a token budget

In an IF node, compare {{ $json.result.inputTokens }} with your limit—for example, 100000. This is useful when your operational limit is smaller than the model's maximum context window.

Compare model cost before routing

Choose Compare Models, select candidate models, and set Expected Output Tokens. Inspect each row in result and route based on cost.total.

Understand and reuse the output

{
  "operation": "count",
  "source": { "characters": 58, "files": [] },
  "result": {
    "modelId": "gpt-5.6-terra",
    "inputTokens": 12,
    "outputTokens": 0,
    "cost": { "input": 0.000024, "output": 0, "total": 0.000024 },
    "context": { "ratio": 0.000011, "remaining": 1049988, "overContext": false }
  }
}

• result.inputTokens: measured input tokens.
• result.cost.total: estimated total USD cost.
• result.context.remaining: tokens remaining in the selected model's context window.
• result.context.overContext: ready-to-use boolean for an IF node.
• source.files: audit metadata for every processed upload.

OpenAI-compatible text uses local BPE tokenization. Other provider families are deterministic estimates; images use provider formulas. Provider billing remains authoritative.

Troubleshooting

• Text shows undefined: execute the previous node and map a field visible in its output.
• No files were counted: choose a binary input mode and use *, the correct prefix wildcard, or exact property names.
• Unsupported file type: extract it first, then pass plain text. PDF/DOCX bytes are not guessed as UTF-8.
• Package cannot be edited in the UI: it was installed through deployment environment variables.
• Old behavior after updating: confirm version 0.1.5 or later, restart n8n, and reopen the editor.

Runtime boundary

Processing occurs inside your n8n runtime. The node requires no TokenCalculator.dev account or API key and does not send workflow content to TokenCalculator.dev. Your deployment still controls execution-data retention, logs, storage, credentials, and access.

n8n installation documentation · Activepieces guide · All integrations