Package Information
Documentation
@cervio/n8n-nodes-cervio

Official n8n community node for Cervio.
Connect n8n workflows to a Cervio tenant over the public REST API (/api/v1): entity records, documents, N:M links, upsert/resolve, workflows, and notifications. Field lists for create/update come from the form write-schema (resource mapper), not a free-form JSON body. The node is marked usableAsTool: true (optional REST tool for AI Agent). For the full Cervio MCP tool surface, use n8n’s built-in MCP Client Tool — see AI Agent + Cervio MCP.
| Website | cervio.app |
| npm | @cervio/n8n-nodes-cervio |
| Source | github.com/cervio-app/n8n-nodes-cervio |
| Issues | GitHub Issues |
| Changelog | CHANGELOG.md |
| Node type | @cervio/n8n-nodes-cervio.cervio |
Maintained by Cervio. Support: Issues or dev@cervio.app.
Migration: the unscoped package
n8n-nodes-cerviois deprecated. Install@cervio/n8n-nodes-cervioand re-select the Cervio credential / node if n8n cached the old type name.
Prerequisites
- Node.js ≥ 20
- An n8n instance (self-hosted, desktop, or Cloud with community packages enabled)
- A Cervio Personal Access Token (
cpat_…) from Admin → API - External API access enabled for the organization
Installation
n8n UI (recommended)
- Open Settings → Community nodes
- Install
@cervio/n8n-nodes-cervio - Restart n8n if prompted
npm + custom folder
npm install -g @cervio/n8n-nodes-cervio
mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm link @cervio/n8n-nodes-cervio
Restart n8n, then add the Cervio node from the palette.
From source
git clone https://github.com/cervio-app/n8n-nodes-cervio.git
cd n8n-nodes-cervio
npm install && npm run build
npm link
mkdir -p ~/.n8n/custom && cd ~/.n8n/custom
npm link @cervio/n8n-nodes-cervio
Docker Compose (local n8n)
Uses compose.yaml with a pinned n8nio/n8n image and this package bind-mounted via N8N_CUSTOM_EXTENSIONS:
npm run build
docker compose -f compose.yaml up
# → http://localhost:5678
Optional image bake: Dockerfile (same pin, N8N_CUSTOM_EXTENSIONS=/opt/n8n-nodes-cervio only).
Live API smoke scripts (npm run smoke*) are separate — see CONTRIBUTING.md.
Credentials
Create a Cervio API credential in n8n:
| Field | Example | Notes |
|---|---|---|
| Base URL | https://acme.cervio.app |
Tenant host only — required, no default. Must be http/https. Link-local / cloud-metadata hosts (169.254.0.0/16, metadata.google.internal, …) are rejected. |
| Personal Access Token | cpat_… |
From Cervio Admin → API |
All operations use this credential.
Operations
Pick a Resource, then an Operation (node typeVersion 2 only):
| Resource | Operation | Description |
|---|---|---|
| Record | Create / Update / Get / Delete | CRUD through an assigned form mask |
| Create or Update (upsert) | Natural-key create-or-update (match_field) |
|
| Validate draft | Dry-run formulas / required fields | |
| List view | Read via an assigned list view (cursor pages) | |
| List | Admin entity list with filter[field]=eq.value |
|
| Relation | Search | Browse/search relation candidates (q, limit ≤ 100) |
| Resolve Key | Match scalar keys → record UUIDs | |
| Link / Unlink | N:M through-field links | |
| Document | List / Upload / Open | Metadata, multipart upload, signed URL |
| Generate from Template | Render a mapped document template (admin) | |
| Workflow | Start / Get Run Status | Manual start + admin run status |
| Notification | Send to Me | Inbox (+ push if enabled) for the PAT owner |
| Notify Users | Up to 50 org members (admin) |
Notes
- Create / Update / Upsert / Validate: pick Entity → Form, then the resource mapper.
- N:M through fields are not on the mapper — use Link / Unlink.
- Relation dropdowns are capped (~50); use Search relation for larger sets.
- List view defaults: options = slugs, relations = UUIDs (ready for Update).
- Start workflow → Additional Data: Key/Value rows or a JSON object (same
databody Cervio accepts onPOST /api/v1/workflows/:id/runs, max 64 KiB →$trigger.data).
Permissions
There is no n8n-specific ACL in Cervio. The node is a REST client; Cervio applies two layers. Both must allow the call.
n8n ──Bearer cpat_…──► 1) PAT scopes (Admin → API)
│ fail → 401 / scope error
▼
2) User who owns the PAT (same ACL as UI)
│ fail → 403 / 404 / empty / validation
Token scopes
| Scope | Used for |
|---|---|
records:read |
Get, List view/records, Search/Resolve, List/Open documents |
records:write |
Create, Update, Delete, Upsert, Validate, Upload, Link/Unlink, Start workflow |
admin:read |
Form / view / workflow dropdowns, Get workflow run |
admin:write |
Generate document from template; Notify Users |
me:write |
Send to Me (self notification) |
*:write implies the matching *:read. Scopes alone do not grant row access or can_create. Org notifications must be enabled or Cervio returns 403 notifications_disabled.
User behind the PAT
The PAT impersonates its owner (entity permissions, record policies, field denials, form/view assignments, document capabilities, manual-workflow trigger ACL) — same as the UI.
| Setup | PAT owner | Scopes |
|---|---|---|
| Full guided UX | system_admin |
admin:read, admin:write, records:read, records:write, me:write |
| Narrow sync | Service user with entity ACL + assigned views/forms | records:read / records:write only |
AI Agent + Cervio MCP
For an AI Agent that should call Cervio’s full MCP tool set (records, forms, workflows, admin tools filtered by PAT scopes), use n8n’s built-in MCP Client Tool — not a custom Cervio MCP node in this package.
- AI Agent → Tool → MCP Client Tool
- Endpoint:
https://YOUR_TENANT.cervio.app/api/mcp(same host as the Cervio API Base URL) - Server Transport: HTTP Streamable (do not use deprecated SSE)
- Authentication: Bearer Auth — create an n8n Bearer credential with the raw PAT
cpat_…only (noBearerprefix) - Tenant: External API enabled for the org; PAT scopes non-empty and adequate for the tools you need (tools outside scope disappear from
tools/list) - Tools to Include: All or a subset
The Bearer credential is a separate n8n credential entry from Cervio API (community node limit): same PAT value, two credential rows.
Optional / narrower: this package’s node is usableAsTool: true, so you can also attach Cervio Tool for a single fixed Resource + Operation (REST). That does not expose the full MCP surface.
We intentionally do not ship a wrapper MCP client here: n8n owns transport and protocol updates; a thin Cervio-branded MCP Tool (reuse cervioApi credential, auto URL) may come later if onboarding friction justifies it.
Compatibility
| n8n | Community nodes API v1 (n8nNodesApiVersion: 1); local Compose pin n8nio/n8n:2.47.2 |
| Node.js | ≥ 20 (build / smoke); CI uses Node 22 |
| Cervio | Tenant with /api/v1 and External API enabled |
| Node typeVersion | 2 only (Resource + Operation) |
Development
npm install
npm run build
npm test
npm run verify
npm run lint
Conventions, SemVer tags (vX.Y.Z), and publish steps: CONTRIBUTING.md.
Live smoke (optional):
export CERVIO_BASE_URL=https://YOUR_TENANT.cervio.app
export CERVIO_PAT=cpat_…
npm run smoke
npm run smoke:extended
Known limits
- List records without a view is admin-only — prefer List view
- Nested child create = two Creates (parent, then child with FK)
- Generate document needs a mapped template UUID (no public template catalog yet)
- List view “all pages”: max 10 × 500 rows
Code of Conduct
See CODE_OF_CONDUCT.md.
References
- Cervio
- n8n community nodes
- Tenant OpenAPI:
public/openapi/v1.yamlin the Cervio app repo