n8n-nodes-backstage

Query your Backstage software catalog, TechDocs, and service dependency graphs directly from n8n workflows and AI Agents — powered by the backctl MCP server.

Installation

Install this community node in your n8n instance:

npm install n8n-nodes-backstage

Or via the n8n UI: Settings → Community Nodes → Install → n8n-nodes-backstage

Prerequisites

A running backctl MCP server accessible via HTTP (Streamable HTTP transport). The server exposes Backstage catalog data through the Model Context Protocol.

Credentials

Configure the Backstage MCP API credential with:

| Field | Description | |-------|-------------| | MCP Server URL | Full URL of the backctl MCP endpoint (e.g. http://backctl-mcp:8080/mcp) | | Bearer Token | Optional. Required when the MCP server is behind an auth gateway (OIDC/Keycloak). Leave empty for unauthenticated access. |

Nodes

Backstage

A regular n8n node for workflow automation. Supports usableAsTool: true so it can also be attached to AI Agents directly.

Operations:

| Operation | Description | Key Parameters | |-----------|-------------|----------------| | Search | Free-text search across catalog and TechDocs | query, searchType, limit | | Get Entity | Get full entity details by ref | ref (e.g. component:default/my-service) | | List Entities | List/filter catalog entities | kind, filter, limit, cursor | | Get TechDocs Page | Fetch a documentation page as text | ref, path | | List TechDocs Pages | Table of contents for an entity | ref | | Get Relationships | Traverse dependency graph | ref, direction, relationType, depth | | Execute Command | Run any backctl CLI subcommand | command |

Backstage AI Tool

An AI Tool sub-node designed for use with n8n's AI Agent node. It exposes selected Backstage operations as LangChain-compatible tools that the agent can invoke autonomously during conversations.

Configure which operations the agent can access via the Available Operations multi-select.

Usage Examples

Workflow Automation

1. Catalog Audit — Use a Schedule trigger + Backstage (List Entities) to periodically check for components missing ownership or lifecycle annotations.
2. Dependency Impact Analysis — When a service is updated, use Get Relationships to find all downstream consumers and notify their owners.
3. TechDocs Sync — Fetch documentation pages and push them to Confluence or Notion.

AI Agent (RAG)

Connect the Backstage AI Tool node to an AI Agent. The agent can then answer questions like:

• "Who owns the payment-gateway service?"
• "What APIs does the ride-service consume?"
• "Show me the onboarding docs for the driver platform"

Development

# Install dependencies
npm install

# Build (TypeScript + esbuild bundling)
make build

# Lint
make lint

# Run n8n locally with the node loaded (builds + Docker image + starts container)
# Access n8n at http://localhost:5678
make run

# Clean build artifacts, node_modules, Docker image, and dev volume
make clean

Make targets

| Target | Description | |--------|-------------| | make build | Compile TypeScript and bundle with esbuild (npm run build) | | make lint | Run linter (npm run lint) | | make docker | Build + create Docker dev image (n8n-backstage-dev) | | make run | Build + Docker + run n8n at localhost:5678 (data persisted in a Docker volume) | | make release | Lint + build + interactive release (bump version, tag, push, publish via CI) | | make info | Show published package info from npm registry | | make clean | Remove dist/, node_modules/, Docker container, image, and dev volume |

License

MIT