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.