TCP Server Trigger

Start a TCP server and trigger workflow when data is received

Overview

This node implements a TCP server trigger that listens on a specified host and port for incoming TCP connections. When data is received from a client, it triggers the workflow with the received data and connection details. This node is useful for scenarios where you want to integrate n8n workflows with devices or applications that communicate over raw TCP sockets, such as IoT devices, custom network protocols, or legacy systems sending data via TCP.

Practical examples:

Receiving sensor data from an IoT device that sends periodic updates over TCP.
Integrating with a legacy system that pushes logs or events via TCP connections.
Acting as a simple TCP endpoint to collect messages from various clients and process them in n8n.

Properties

Name	Meaning
Port	Port number on which the TCP server will listen (1–65535).
Host	IP address or hostname to bind the TCP server to. Use `127.0.0.1` for localhost or `0.0.0.0` for all interfaces.
Options.Encoding	Text encoding used to decode incoming data. Options: UTF-8, ASCII, Base64, Hex.
Options.Max Connections	Maximum number of simultaneous TCP connections allowed (1–1000).
Options.Keep Connection Open	Whether to keep the TCP connection open after receiving data (`true` or `false`).
Options.Send Response	Whether to send a response message back to the client after receiving data (`true` or `false`).
Options.Response Message	The message text to send back to the client if "Send Response" is enabled.

Output

The node outputs JSON data each time it receives data from a TCP client. The output structure includes:

protocol: Always "tcp".
server: Object containing the server's host and port.
client: Object with client connection details: remoteAddress, remotePort, localAddress, localPort.
data: The received data decoded as a string using the selected encoding.
encoding: The text encoding used to decode the data.
bytes: Number of bytes received.
timestamp: ISO timestamp when the data was received.
keepConnectionOpen: Boolean indicating if the connection remains open after data receipt.
responseSent: Boolean indicating if a response message was sent back to the client.

Additionally, the node outputs the raw binary data under the binary.data field encoded as base64 with MIME type application/octet-stream.

If the option to send a response is enabled, the node writes the configured response message back to the client before optionally closing the connection.

Dependencies

Uses Node.js built-in net module to create the TCP server.
No external API keys or services are required.
Requires appropriate permissions and network access to bind to the specified host and port.
Ensure no other service is using the chosen port to avoid conflicts.

Troubleshooting

Port already in use error: If the node throws an error indicating the port is already in use, choose a different port or stop the conflicting service.
Permission denied error: Binding to ports below 1024 may require elevated privileges; use higher port numbers or run with sufficient permissions.
Data encoding issues: If received data appears corrupted or unreadable, verify the correct encoding is selected matching the client's data format.
Connection handling: If clients disconnect unexpectedly, check network stability and whether the "Keep Connection Open" option suits your use case.
Response not received by client: Ensure "Send Response" is enabled and the response message is correctly set.