Guide: n8n MCP client stdio: how to connect?

This tutorial shows how to connect an n8n MCP client over stdio using Node.js and Docker. To connect the n8n MCP client stdio you run a small Node.js process that speaks the MCP protocol on stdin/stdout and start it alongside n8n; the example below uses a minimal script and Docker commands so you can test locally.

What You Need

• Docker installed on your machine.
• Node.js (v16 or later) for the local example.
• Basic terminal or shell access.
• An n8n instance (Docker recommended) to integrate later.

How to connect n8n MCP client stdio

We build a simple MCP client that reads JSON messages line-by-line from stdin and writes JSON responses to stdout. You can run it with Node.js or build a small Docker image and run it interactively so n8n can communicate over stdio.

Step 1: Create the Node.js MCP client

Save this file as mcp-client-stdio.js. It reads lines, parses JSON, handles a handshake, and replies.

const readline = require('readline');
const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
rl.on('line', (line) => {
  try {
    const msg = JSON.parse(line);
    if (msg.type === 'handshake') {
      const resp = { type: 'handshake_ok', version: 1 };
      process.stdout.write(JSON.stringify(resp) + '\n');
      return;
    }
    // Example: echo back a simple result
    const resp = { type: 'result', id: msg.id || null, ok: true };
    process.stdout.write(JSON.stringify(resp) + '\n');
  } catch (err) {
    const errMsg = { type: 'error', message: 'invalid json' };
    process.stdout.write(JSON.stringify(errMsg) + '\n');
  }
});

Step 2: Run the client locally with Node

Run the client to listen on stdin/stdout. Keep the terminal open so it can communicate with n8n or a test sender.

node mcp-client-stdio.js

Step 3: Build and run as a Docker container (optional)

Create a Dockerfile that uses a Node image and copies the script. This example runs interactively to keep stdin open.

FROM node:18-alpine
WORKDIR /app
COPY mcp-client-stdio.js /app/mcp-client-stdio.js
CMD ["node", "mcp-client-stdio.js"]

Build and run:

docker build -t mcp-client-stdio .
docker run --rm --name mcp-client -i mcp-client-stdio

Step 4: Test messages manually

You can test the client by sending JSON lines to its stdin. In a different terminal use:

printf '{"type":"handshake"}\n' | docker run -i --rm mcp-client-stdio
# or locally
printf '{"type":"handshake"}\n' | node mcp-client-stdio.js

The client writes JSON responses to stdout. Use the same pattern to simulate n8n messages for development and debugging.

Update

Keep your Node.js and Docker images updated. Rebuild the Docker image after code changes. Use clear version tags in production builds to avoid accidental upgrades.

Security

• Validate and sanitize all incoming JSON messages.
• Run the client in an isolated container or limited user account.
• Limit CPU and memory for the container to reduce risk from malformed inputs.
• Do not run untrusted code inside the client process.

Done

You now have a minimal MCP client that communicates over stdio. Next, consult your n8n instance configuration to point n8n at this client process or use it for local development. Use the test commands above to verify the handshake and message flow before integrating into production.