n8n-nodes-kusto

This is an n8n community node that lets you execute KQL queries against Azure Data Explorer (Kusto) clusters directly from your n8n workflows.

It authenticates via Azure AD service principal (client credentials) or OAuth2 Authorization Code flow and calls the Kusto REST API to run queries and management commands, returning rows as JSON items.

n8n is a fair-code licensed workflow automation platform.

---

Table of Contents

• Installation
• Prerequisites
• Credentials
• Node Reference
• Usage Examples
• Development
• Compatibility
• License
• AI Transparency
• Contributing

---

Installation

Follow the installation guide in the n8n community nodes documentation.

Via n8n UI

1. Go to Settings → Community Nodes
2. Enter n8n-nodes-kusto
3. Click Install

Via npm (self-hosted)

cd ~/.n8n
npm install n8n-nodes-kusto

Then restart your n8n instance.

---

Prerequisites

1. An Azure Data Explorer cluster (e.g. https://mycluster.westeurope.kusto.windows.net)
2. One of the following authentication methods:

Option A: Service Principal (Client Credentials)

Best for server-to-server automation where no interactive sign-in is needed.

1. An Azure AD (Entra ID) App Registration with:
   • A client secret
   • Permissions granted on the Kusto cluster (viewer / admin role)
2. The tenant ID, client ID, and client secret from the app registration

Setting up Service Principal credentials

1. Go to Azure Portal → App registrations
2. Register a new application (or use an existing one)
3. Under Certificates & secrets, create a new client secret — save it
4. In your Kusto cluster, grant the app permissions:

   .add database MyDatabase viewers ('aadapp=<client-id>;<tenant-id>')
   

5. Note your Tenant ID (from Azure AD overview), Client ID (from app overview), and the Client Secret value

Option B: OAuth2 Authorization Code

Best for interactive / cross-tenant scenarios where the user signs in via browser.

1. An Azure AD (Entra ID) App Registration with:
   • A Web redirect URI: https://<your-n8n-host>/rest/oauth2-credential/callback
   • API permissions: Azure Data Explorer → user_impersonation (delegated)
   • For multi-tenant access: set the app to Accounts in any organizational directory
2. The tenant ID (or common / organizations for multi-tenant), client ID, and client secret

---

Credentials

Kusto API (Service Principal)

Select Authentication Type → Service Principal in the node, then add Kusto API credentials:

Field	Description
Tenant ID	Azure AD (Entra ID) tenant ID (GUID)
Client ID	Azure AD application (client) ID (GUID)
Client Secret	Azure AD application client secret (stored securely)

Kusto OAuth2 API

Select Authentication Type → OAuth2 in the node, then add Kusto OAuth2 API credentials:

Field	Description
Tenant ID	Azure AD tenant ID — use common or organizations for multi-tenant (default: common)
Cluster URL	Azure Data Explorer cluster URL — used to scope the access token
Grant Type	Authorization Code (interactive sign-in) or Client Credentials (app-only)
Client ID	Azure AD application (client) ID
Client Secret	Azure AD application client secret

After saving, click Connect (for Authorization Code) to sign in via the browser. n8n manages token refresh automatically.

---

Node Reference

Kusto Query

Operations:

Operation	Description
Query	Execute a read-only KQL query
Management Command	Execute a control command (e.g. .show tables)

Parameters:

Parameter	Type	Required	Description
Authentication Type	select	✅	Service Principal or OAuth2
Cluster URL	string	✅	Azure Data Explorer cluster endpoint URL
Database	string	✅	Target database name
KQL Query	string	✅	The KQL query or management command to execute

Options:

Option	Type	Default	Description
Server Timeout	string	4m	Server-side query timeout (e.g. 10m, 1h)
No Truncation	boolean	false	Disable result truncation (return all rows)
Client Request ID	string		Custom request ID for tracing

---

Usage Examples

Example 1: Simple query

1. Add a Manual Trigger node
2. Connect a Kusto Query node
3. Configure:
   • Cluster URL: https://mycluster.westeurope.kusto.windows.net
   • Database: MyDatabase
   • KQL Query: StormEvents | take 10
4. Execute the workflow

Each row from the result set is returned as a separate n8n item with all columns as JSON properties.

Example 2: Aggregation query

StormEvents
| summarize EventCount = count() by State
| top 5 by EventCount desc

Returns items like:

[
  { "State": "TEXAS", "EventCount": 4701 },
  { "State": "KANSAS", "EventCount": 3166 },
  ...
]

Example 3: Management command

Set Operation to Management Command and use:

.show tables

Returns one item per table with columns like TableName, DatabaseName, Folder, etc.

Example 4: Using expressions

You can use n8n expressions in the KQL Query field:

{{ $json.tableName }} | where Timestamp > ago({{ $json.hours }}h) | count

---

Development

Build

git clone https://github.com/sergey-goncharenko/n8n-community-kusto.git
cd n8n-community-kusto
npm install
npm run build

Test locally with n8n

# In the n8n-nodes-kusto directory:
npm link

# In the n8n directory (or ~/.n8n):
npm link n8n-nodes-kusto

# Restart n8n
n8n start

Lint

npm run lint
npm run lintfix

---

Compatibility

n8n Version	Compatible
≥ 1.0.0	✅

• Node.js: ≥ 18.0.0
• Azure Data Explorer REST API: v1

---

License

MIT

---

🤖 AI Transparency

This project was developed with AI-assisted tooling:

• GitHub Copilot in VS Code — powered by Claude Opus 4.6 (Anthropic) for code generation, architecture decisions, and iterative development
• GitHub.com Copilot — for code review, CI/CD pipeline design, and npm publishing workflow
• Microsoft Copilot — for Azure Data Explorer API research and documentation

All AI-generated code was reviewed, tested, and validated by the maintainer against live Azure Data Explorer clusters.

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on:

• Reporting bugs and requesting features
• Setting up the development environment
• Submitting pull requests
• Coding standards and commit conventions

Please read our Code of Conduct before participating.