n8n-mcp-community

# n8n MCP Community

**A security-focused Model Context Protocol server for self-hosted n8n Community Edition.**

Connect an MCP client to the **full n8n management surface**: create, edit,
activate, and delete workflows, update individual nodes surgically, and manage
executions, credentials, tags, users, diagnostics, and instance metadata — 44
carefully bounded tools in total. Safety here is **progressive, not
restrictive**: the server defaults to read-only, `write` unlocks authoring,
and `unsafe` unlocks every tool with an exact per-call confirmation phrase for
each destructive operation. It starts offline, uses the supported n8n Public
API, and never sends workflow data to an external AI provider.

> **v0.1.1 is published:** exact-version npm
> ([`n8n-mcp-community@0.1.1`](https://www.npmjs.com/package/n8n-mcp-community)
> with provenance attestations), a signed MCPB in the
> [v0.1.1 release](https://github.com/drzamarian/n8n-mcp-community/releases/latest),
> and the MCP Registry entry `io.github.drzamarian/n8n-mcp-community`. See
> [Installation](docs/installation.md).

[Read the synthetic terminal demo transcript](docs/demo-transcript.md). It shows
the exact-version startup, 44-tool inventory, and local Introspect
diagnostics using only synthetic identifiers and documented output shapes.

[![Animated synthetic terminal demonstration showing the exact-version startup, MCP inventory, and local Introspect result](docs/assets/demo.gif)](docs/demo-transcript.md)

## Why this project

- **Community Edition first.** The release surface is designed for self-hosted
  n8n Community Edition, without presenting paid-only capabilities as available.
- **44 useful tools, one explicit contract.** Every tool has bounded inputs,
  documented side effects, MCP safety annotations, and contract tests.
- **Safe by default.** Read-only mode is the default. Writes and destructive or
  externally contacting operations require progressively stronger gates.
- **Deterministic Introspect.** `n8n_introspect` runs a local 23-rule engine;
  it does not execute workflows, call an agent, or contact an external model.
- **Surgical node updates.** `n8n_update_node` changes one validated node path
  while preserving the rest of the workflow and disclosing the Public API's
  non-atomic limitation.
- **Truthful discovery.** `n8n_list_node_types` reports only types observed in
  accessible workflows. It does not claim to be a complete installed catalog.
- **Data minimization.** Credential values, raw execution values, pin data, and
  static workflow data are not returned by the generic public tools.

## Current verification

The current source candidate has been verified with:

- exactly **44 tools**, **5 resources**, and **4 prompts** over real stdio;
- **271 passing tests** and the complete verification gate on Node.js 22.23.1
  and 24.18.0;
- zero findings from Gitleaks, Semgrep, Trivy, and both production/full
  `npm audit` runs; all three source scanners are reproduced in CI, with
  immutable scanner/action identities;
- a reproducible dependency-license gate covering 224 installed package paths;
- bounded same-origin HTTP contracts and zero-request policy-denial tests;
- all 44 compiled tool lifecycles on disposable n8n Community 2.30.5 and 2.30.7
  instances with egress isolation, revoked keys, cleanup, and zero residue; and
- a clean-installed npm tarball plus a byte-reproducible unsigned MCPB with the
  same compiled runtime and complete production dependency notices.

Publication proceeds only through the reviewed release procedure: the
repository-pinned MCPB signing identity, a human artifact-baseline receipt,
tag-scoped protected-environment approval, and an externally signed MCPB
handoff verified byte for byte against the reviewed unsigned candidate.

## Quick start

Requirements: Node.js 22 or 24, npm, a self-hosted n8n Community Edition
instance, and an n8n Public API key with only the permissions you need.

Configure your MCP client to run the published exact version:

```json
{
  "mcpServers": {
    "n8n-community": {
      "command": "npx",
      "args": ["--yes", "n8n-mcp-community@0.1.1"],
      "env": {
        "N8N_API_URL": "https://n8n.example.com",
        "N8N_API_KEY": "replace-with-a-dedicated-api-key",
        "N8N_MCP_MODE": "read-only"
      }
    }
  }
}
```

`read-only` is the recommended starting point, not a capability ceiling: the
same 44-tool surface includes full workflow authoring. Set
`N8N_MCP_MODE=write` to create and edit workflows, nodes, credentials, and
tags, or `N8N_MCP_MODE=unsafe` to enable every tool — activation, deletion,
retries, and the other destructive operations, each still guarded by an exact
per-call confirmation phrase. See [Safety modes](#safety-modes).

Restart the MCP client and confirm exactly 44 tools, 5 resources, and 4
prompts. Compatible desktop clients can instead install the signed MCPB from
the
[v0.1.1 release](https://github.com/drzamarian/n8n-mcp-community/releases/latest);
verify its checksum against the release `SHA256SUMS` first.

## Quick start from source

Requirements: Node.js 22 or 24, npm, and a Git checkout of this repository.

```bash
npm ci
npm run build
```

Configure your MCP client to run the compiled stdio entry point:

```json
{
  "mcpServers": {
    "n8n-community": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp-community/dist/index.js"],
      "env": {
        "N8N_API_URL": "https://n8n.example.com",
        "N8N_API_KEY": "replace-with-your-api-key",
        "N8N_MCP_MODE": "read-only"
      }
    }
  }
}
```

Restart the MCP client and list tools. The server can initialize and expose its
inventory without n8n credentials; connected tools validate the URL and API key
only when called.

The release provides both a signed MCPB for compatible clients and
exact-version `npx` configuration for portability. `@latest`, global installs,
and `curl | shell` are not reproducible defaults. See
[Installation](docs/installation.md) for the release policy and client-specific
guidance.

## Safety modes

| Mode      | What it allows                                                    | Required configuration                                     |
| --------- | ----------------------------------------------------------------- | ---------------------------------------------------------- |
| Read-only | Read-only tools only                                              | Default, or `N8N_MCP_MODE=read-only`                       |
| Write     | Read-only and mutation tools without the unsafe confirmation gate | `N8N_MCP_MODE=write`                                       |
| Unsafe    | All tools                                                         | `N8N_MCP_MODE=unsafe` plus the exact per-call confirmation |

Unsafe mode is necessary but not sufficient. Every unsafe call also requires a
confirmation such as `DELETE wf_123`, `STOP exec_123`, or `TEST cred_123`.
The n8n API key remains the final upstream permission boundary.

Plain HTTP is accepted automatically only for loopback URLs. A non-loopback
HTTP instance additionally requires `N8N_ALLOW_INSECURE_HTTP=1`, which accepts
the risk of exposing the API key and data in transit.

## Tool catalog

Every entry links to its complete input, output, endpoint, compatibility,
failure, and security reference.

### Workflows

| Tool                                                                   | Mode      | Purpose                                                                |
| ---------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------- |
| [`n8n_workflows_list`](docs/tools.md#n8n_workflows_list)               | Read-only | List accessible workflows with bounded filters and pagination.         |
| [`n8n_workflows_get`](docs/tools.md#n8n_workflows_get)                 | Read-only | Read one workflow while withholding pin and static data values.        |
| [`n8n_workflows_create`](docs/tools.md#n8n_workflows_create)           | Write     | Create a validated workflow through the Public API.                    |
| [`n8n_workflows_update`](docs/tools.md#n8n_workflows_update)           | Write     | Guard and update selected fields while preserving omitted fields.      |
| [`n8n_update_node`](docs/tools.md#n8n_update_node)                     | Write     | Change one validated node property with non-atomic concurrency guards. |
| [`n8n_workflows_delete`](docs/tools.md#n8n_workflows_delete)           | Unsafe    | Permanently delete one workflow after exact confirmation.              |
| [`n8n_workflows_activate`](docs/tools.md#n8n_workflows_activate)       | Unsafe    | Activate one workflow after exact confirmation.                        |
| [`n8n_workflows_deactivate`](docs/tools.md#n8n_workflows_deactivate)   | Unsafe    | Deactivate one workflow after exact confirmation.                      |
| [`n8n_workflows_get_version`](docs/tools.md#n8n_workflows_get_version) | Read-only | Retrieve one retained historical workflow version.                     |
| [`n8n_workflows_get_tags`](docs/tools.md#n8n_workflows_get_tags)       | Read-only | List tags assigned to a workflow.                                      |
| [`n8n_workflows_update_tags`](docs/tools.md#n8n_workflows_update_tags) | Write     | Replace a workflow's complete tag assignment.                          |
| [`n8n_workflows_archive`](docs/tools.md#n8n_workflows_archive)         | Unsafe    | Archive one workflow after exact confirmation.                         |
| [`n8n_workflows_unarchive`](docs/tools.md#n8n_workflows_unarchive)     | Unsafe    | Restore one archived workflow after exact confirmation.                |
| [`n8n_workflows_diff`](docs/tools.md#n8n_workflows_diff)               | Read-only | Compare nodes and connections without returning raw values.            |

### Executions

| Tool