> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/workflow-sdk.md).

# Workflow SDK

Describe n8n workflows as TypeScript code with the Workflow SDK, the format that the n8n MCP server builder tools and n8n AI use to create workflows.

The Workflow SDK lets you describe an n8n workflow as code. You declare triggers and nodes, connect them with `.add()` and `.to()`, and export the result. The SDK turns that code into the same workflow JSON the editor uses, and validates it.

SDK code is a restricted subset of TypeScript. n8n reads it with an interpreter, and the code never runs.

{% hint style="info" %}
**Feature availability**

The Workflow SDK builder tools on the n8n MCP server are available from n8n 2.12.0. The SDK is the `@n8n/workflow-sdk` package on npm. You don't need to install it to use the MCP builder tools.
{% endhint %}

## Who uses the Workflow SDK

Three parts of n8n read Workflow SDK code:

* The [n8n MCP server](https://docs.n8n.io/connect/connect-to-n8n-mcp-server.md) builder tools. `validate_workflow` checks the code, `create_workflow_from_code` saves it as a workflow, and `update_workflow` changes an existing workflow. Refer to the [MCP server tools reference](https://docs.n8n.io/connect/connect-to-n8n-mcp-server/mcp-server-tools-reference.md#workflow-builder).
* n8n AI, which writes Workflow SDK code when it builds a workflow for you.
* AI coding agents such as Claude Code or Cursor, when they connect to the n8n MCP server.

## Turn code into a workflow

There are two ways to turn SDK code into a workflow on your instance:

* **Through the n8n MCP server.** Send the code to `validate_workflow`, then to `create_workflow_from_code`. The instance parses the code, so you don't install anything. This needs n8n 2.12.0 or later, and an owner or admin must first [enable MCP access](https://docs.n8n.io/connect/connect-to-n8n-mcp-server.md#enabling-mcp-access). The [Quickstart](https://docs.n8n.io/connect/workflow-sdk/quickstart.md) walks through this path.
* **Locally, with the package.** Install `@n8n/workflow-sdk` from npm. Convert the code to workflow JSON with `parseWorkflowCodeToBuilder`, then check it with `validateWorkflowBuilder`. Then create the workflow from that JSON with the [n8n API](https://docs.n8n.io/connect/n8n-api.md) or the [n8n CLI](https://docs.n8n.io/connect/n8n-cli.md). The parser doesn't accept `import` lines, so remove them before you parse. Refer to [Convert code to workflow JSON](https://github.com/n8n-io/n8n/blob/master/packages/@n8n/workflow-sdk/README.md#convert-code-to-workflow-json) in the SDK README.

The n8n API and the n8n CLI work with workflow JSON. They don't read SDK code.

## What the code looks like

A workflow is a chain of calls. This example runs a manual trigger, fetches a GitHub repository, and keeps its star count:

```typescript
import { workflow, node, trigger, expr } from '@n8n/workflow-sdk';

const start = trigger({
  type: 'n8n-nodes-base.manualTrigger',
  version: 1,
  config: { name: 'Start' }
});

const fetchRepo = node({
  type: 'n8n-nodes-base.httpRequest',
  version: 4.3,
  config: {
    name: 'Fetch repository',
    parameters: { method: 'GET', url: 'https://api.github.com/repos/n8n-io/n8n' }
  }
});

const keepStars = node({
  type: 'n8n-nodes-base.set',
  version: 3.4,
  config: {
    name: 'Keep stars',
    parameters: {
      mode: 'manual',
      includeOtherFields: false,
      assignments: {
        assignments: [
          { id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
        ]
      }
    }
  }
});

export default workflow('github-stars', 'GitHub stars')
  .add(start)
  .to(fetchRepo)
  .to(keepStars);
```

Every file exports one workflow with `export default workflow(...)`. Node types and parameter names are the same as in workflow JSON. Expressions use `expr()` around the `{{ }}` syntax you know from the editor.

## SDK reference

The SDK reference lives with the SDK code:

* The [SDK README](https://github.com/n8n-io/n8n/blob/master/packages/@n8n/workflow-sdk/README.md) covers installing the package, a working example, and converting code to workflow JSON.
* For the full reference, call `get_workflow_sdk_reference` on the [n8n MCP server](https://docs.n8n.io/connect/connect-to-n8n-mcp-server/mcp-server-tools-reference.md#workflow-builder). It returns the builder functions, language rules, patterns, and expressions for the SDK version your instance runs.

## In this section

* [Quickstart](https://docs.n8n.io/connect/workflow-sdk/quickstart.md): write your first workflow file, check it, and create it on your instance.
* [Build with AI](https://docs.n8n.io/connect/workflow-sdk/build-with-ai.md): everything an AI coding agent needs to write Workflow SDK code for your instance.

## Which package is this

`@n8n/workflow-sdk` describes workflows. It isn't the n8n public API client, it isn't the `@n8n/cli` command-line tool, and it isn't the framework for building [custom nodes](https://docs.n8n.io/connect/create-nodes.md). For the MCP path you don't need to install it, because the n8n instance parses the code. Install it to convert code locally, or to get TypeScript types in your editor.

The Workflow SDK works with n8n Cloud and self-hosted instances.

## Related resources

* [Connect](https://docs.n8n.io/connect/readme.md)
* [n8n API](https://docs.n8n.io/connect/n8n-api.md)
* [n8n CLI](https://docs.n8n.io/connect/n8n-cli.md)
* [Connect to n8n MCP server](https://docs.n8n.io/connect/connect-to-n8n-mcp-server.md)
* [Connect to the n8n docs MCP server](https://docs.n8n.io/connect/connect-to-n8n-docs-mcp-server.md)
* [Create nodes](https://docs.n8n.io/connect/create-nodes.md)
* [MCP server tools reference](https://docs.n8n.io/connect/connect-to-n8n-mcp-server/mcp-server-tools-reference.md#workflow-builder)
