n8n-nodes-grpc

An n8n community node for making unary gRPC calls from your workflows. Point it at any gRPC server, paste your .proto files (or let server reflection discover the schema), pick a service and method, and send a JSON payload — no code generation required.

Features

• Unary gRPC calls — request/response with automatic protobuf serialization
• Manual proto files — paste one or more .proto files with full import support; Google well-known types are built-in
• Server reflection — auto-discover services and methods without proto files
• TLS / mTLS / insecure — choose transport security per credential
• Bearer token auth — optional token sent as authorization metadata
• Custom call metadata — arbitrary key-value pairs per request
• Per-request timeout — configurable in milliseconds (default 30 000)
• Merge with Proto Defaults — generates a skeleton from the schema and deep-merges your payload on top
• Credential connectivity test — auto-tests the connection when you save credentials
• AI agent integration — usableAsTool enabled for use in n8n AI workflows

Installation

Follow the installation guide in the n8n community nodes documentation.

This node is self-hosted only — it is not compatible with n8n Cloud (see n8n Cloud below).

Credentials

Create a gRPC API credential with the following fields:

| Field | Type | Default | Description | |-------|------|---------|-------------| | Host | string | — | Hostname and port of the gRPC server (e.g. localhost:50051) | | TLS Mode | options | Insecure | Transport security: Insecure, TLS, or mTLS | | CA Certificate | string | — | CA certificate in PEM format (shown for TLS / mTLS) | | Client Certificate | string | — | Client certificate in PEM format (shown for mTLS) | | Client Key | string | — | Client private key in PEM format (shown for mTLS) | | Auth Token | string | — | Optional Bearer token sent as authorization metadata |

The credential automatically tests connectivity when you save it.

Usage

1. Add a gRPC Request node to your workflow.
2. Create or select a gRPC API credential.
3. Choose a Proto Source — Manual (paste .proto files) or Server Reflection (auto-discover).
4. If Manual: add one or more proto files with a filename and content.
5. Select a Service from the dropdown.
6. Select a Method from the dropdown.
7. Write the JSON Request Payload.
8. Optionally enable Merge with Proto Defaults to fill in missing fields with proto default values.
9. Optionally add Metadata key-value pairs.
10. Set a Timeout if the default 30 000 ms is not appropriate.
11. Execute the node.

Node Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Proto Source | options | Manual | How to obtain the protobuf schema — Manual or Server Reflection | | Proto Files | fixedCollection | — | Proto file entries (filename + content); shown when Proto Source is Manual | | Service | resourceLocator | — | The gRPC service to call | | Method | resourceLocator | — | The method to invoke on the selected service | | Request Payload | json | {} | JSON payload to send with the gRPC request | | Merge with Proto Defaults | boolean | false | Generate a skeleton from the schema and deep-merge your payload on top | | Metadata | fixedCollection | — | Key-value pairs sent as gRPC call metadata | | Timeout | number | 30000 | Request timeout in milliseconds |

Merge with Proto Defaults

When enabled, the node generates a JSON skeleton from the protobuf message definition (all fields set to their proto default values) and deep-merges your request payload on top. Fields you omit in the payload receive their proto defaults, ensuring the full message shape is always sent.

n8n Cloud

This node is not compatible with n8n Cloud. It uses @grpc/grpc-js, which requires Node.js built-in modules (net, tls, http2) that are restricted in the Cloud environment.

Install this node on self-hosted n8n instances only.

Compatibility

• Minimum n8n version: 1.71.0 (n8nNodesApiVersion 1)
• Tested with: n8n 2.12.x

Development

Prerequisites

• Node.js 22+
• just command runner

Commands

| Recipe | Description | |--------|-------------| | just build | Compile TypeScript to dist/ | | just dev | Watch mode — starts local n8n with the node loaded | | just lint | Run the n8n node linter | | just lint-fix | Lint and auto-fix | | just format | Run Prettier | | just format-check | Check formatting without writing | | just test | Run unit + integration tests | | just test-unit | Run unit tests only | | just test-int | Run integration tests only | | just test-e2e | Run e2e tests (requires Docker) | | just test-all | Run all test suites | | just test-coverage | Unit + integration with coverage enforcement | | just check | Full pre-publish check: lint + format + tests + build + verify | | just verify | Run the n8n community package scanner |

Test Server

A standalone gRPC server for manual testing. Start it alongside just dev to interact with the node in a real n8n UI.

just gen-certs        # run once to generate self-signed TLS certificates
just test-server-up   # starts the server in the foreground
# in another terminal:
just dev              # opens n8n with the node loaded

The server listens on two ports:

| Port | Transport | |------|-----------| | 50051 | Insecure | | 50052 | TLS (mTLS — requires client certificate) |

Both ports have gRPC server reflection enabled, so you can test both Manual and Server Reflection proto sources.

Services and test scenarios:

| Service | Method | What it tests | |---------|--------|---------------| | TestService | Echo | Basic unary round-trip — returns the request message verbatim | | | EchoTagged | Nested messages and repeated fields survive serialization | | | Ping | Empty request/response (google.protobuf.Empty) | | | ErrorNotFound, ErrorInvalidArgument, ErrorUnauthenticated, ErrorPermissionDenied, ErrorAlreadyExists, ErrorResourceExhausted, ErrorInternal, ErrorUnavailable, ErrorUnimplemented, ErrorDataLoss | Each returns its respective gRPC status code — tests error mapping | | | SlowResponse | Sleeps for delay_ms before responding — tests timeout behavior | | | EchoMetadata | Returns all incoming call metadata — tests custom metadata pairs | | | ReadRequestId | Returns the x-request-id metadata value | | | RequireAuth | Requires Bearer test-token — tests credential auth token | | | RequireAdminAuth | Requires Bearer admin-* — tests auth with role-based tokens | | | GenerateItems | Returns a repeated field with N items — tests large payloads | | WellKnownTypeService | GetServerTime | Returns a google.protobuf.Timestamp — tests well-known type handling | | | EchoStruct | Echoes a google.protobuf.Struct — tests dynamic JSON payloads |

Test Suites

• Unit tests (test/unit/) — proto parsing, reflection, skeleton generation, merge logic, error mapping, node definition, execute logic
• Integration tests (test/integration/) — in-process gRPC server, full node execute round-trips
• E2E tests (test/e2e/) — real Qdrant (Docker) and Temporal servers
• Manual testing — start the test server with just test-server-up, then use just dev to open n8n with the node loaded and test interactively against the local gRPC server

Generating TLS Certificates

just gen-certs

Run once before starting the TLS test server. Certificates are written to test-server/certs/.

Publishing

1. Run npm run release locally — this bumps the version, updates the changelog, commits, tags, pushes to GitHub, and creates a GitHub release.
2. The pushed version tag (v*.*.*) triggers GitHub Actions, which automatically publishes the package to npm with provenance.

Design & Planning

See DESIGN.md for architecture docs, epics, and stories.

Resources

• n8n community nodes documentation
• gRPC documentation
• Protocol Buffers language guide

Version History

See CHANGELOG.md.