@thecodesaiyan/tcs-n8n-mcp 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nigel Tatschner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @thecodesaiyan/tcs-n8n-mcp
+
+By [@TheCodeSaiyan](https://github.com/ntatschner)
+
+An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for managing [n8n](https://n8n.io) workflow automation instances. Provides 22 tools for workflows, executions, tags, variables, credentials, and users.
+
+## Quick Start
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "n8n": {
+      "command": "npx",
+      "args": ["-y", "@thecodesaiyan/tcs-n8n-mcp"],
+      "env": {
+        "N8N_API_URL": "http://localhost:5678",
+        "N8N_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `~/.claude.json` under `mcpServers`, or run:
+
+```bash
+claude mcp add n8n -- npx -y @thecodesaiyan/tcs-n8n-mcp
+```
+
+Then set the environment variables `N8N_API_URL` and `N8N_API_KEY`.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `N8N_API_KEY` | Yes | — | n8n API key ([how to create](https://docs.n8n.io/api/authentication/)) |
+| `N8N_API_URL` | No | `http://localhost:5678` | Base URL of your n8n instance |
+
+## Available Tools (22)
+
+### Workflows (8)
+
+| Tool | Description |
+|------|-------------|
+| `list_workflows` | List all workflows with pagination |
+| `get_workflow` | Get full workflow details by ID |
+| `create_workflow` | Create a new workflow |
+| `update_workflow` | Update an existing workflow |
+| `delete_workflow` | Delete a workflow (irreversible) |
+| `activate_workflow` | Activate a workflow's triggers |
+| `deactivate_workflow` | Deactivate a workflow |
+| `execute_workflow` | Execute a workflow immediately |
+
+### Executions (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_executions` | List executions with filters |
+| `get_execution` | Get execution details and results |
+| `delete_execution` | Delete an execution record |
+
+### Tags (4)
+
+| Tool | Description |
+|------|-------------|
+| `list_tags` | List all tags |
+| `create_tag` | Create a new tag |
+| `update_tag` | Rename a tag |
+| `delete_tag` | Delete a tag |
+
+### Variables (4)
+
+| Tool | Description |
+|------|-------------|
+| `list_variables` | List all variables (values masked) |
+| `create_variable` | Create a new variable |
+| `update_variable` | Update a variable |
+| `delete_variable` | Delete a variable |
+
+### Credentials (1)
+
+| Tool | Description |
+|------|-------------|
+| `list_credentials` | List credentials (metadata only) |
+
+### Users (2)
+
+| Tool | Description |
+|------|-------------|
+| `list_users` | List all users |
+| `get_user` | Get user details |
+
+## Security
+
+- All resource IDs are validated as numeric strings to prevent path traversal
+- Error responses are sanitised to avoid leaking n8n instance internals
+- Variable values are masked in list output to prevent secret exposure
+- All API calls have a 30-second timeout
+- API keys are never logged or exposed in tool output
+- Credentials tool only returns metadata (secrets are never exposed)
+
+## Development
+
+```bash
+git clone https://github.com/ntatschner/tcs-n8n-mcp.git
+cd tcs-n8n-mcp
+npm install
+npm run build
+npm test
+```
+
+### Running locally
+
+```bash
+N8N_API_KEY=your-key N8N_API_URL=http://localhost:5678 npm start
+```
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerWorkflowTools } from "./tools/workflows.js";
+import { registerExecutionTools } from "./tools/executions.js";
+import { registerTagTools } from "./tools/tags.js";
+import { registerVariableTools } from "./tools/variables.js";
+import { registerCredentialTools } from "./tools/credentials.js";
+import { registerUserTools } from "./tools/users.js";
+const N8N_API_URL = process.env.N8N_API_URL || "http://localhost:5678";
+const N8N_API_KEY = process.env.N8N_API_KEY || "";
+if (!N8N_API_KEY) {
+    console.error("N8N_API_KEY environment variable is required");
+    process.exit(1);
+}
+const apiBase = `${N8N_API_URL.replace(/\/$/, "")}/api/v1`;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const n8nFetch = (path, options = {}) => {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    return fetch(`${apiBase}${path}`, {
+        ...options,
+        signal: options.signal ?? controller.signal,
+        headers: {
+            "X-N8N-API-KEY": N8N_API_KEY,
+            "Content-Type": "application/json",
+            ...options.headers,
+        },
+    }).finally(() => clearTimeout(timeoutId));
+};
+const server = new McpServer({
+    name: "@thecodesaiyan/tcs-n8n-mcp",
+    version: "1.0.2",
+});
+// Register all tool modules
+registerWorkflowTools(server, n8nFetch);
+registerExecutionTools(server, n8nFetch);
+registerTagTools(server, n8nFetch);
+registerVariableTools(server, n8nFetch);
+registerCredentialTools(server, n8nFetch);
+registerUserTools(server, n8nFetch);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("@thecodesaiyan/tcs-n8n-mcp v1.0.2 running on stdio (22 tools)");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/tools/credentials.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { ok, err, handleError, safeJson, } from "../types.js";
+import { paginationCursor } from "../validation.js";
+export function registerCredentialTools(server, n8nFetch) {
+    // --- list_credentials ---
+    server.tool("list_credentials", "List all n8n credentials (metadata only — secrets are not exposed). Shows name, type, and creation date.", {
+        limit: z.number().int().positive().max(200).optional().default(50).describe("Max results"),
+        cursor: paginationCursor,
+    }, async ({ limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (limit)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await n8nFetch(`/credentials?${params}`);
+        if (!res.ok)
+            return handleError(res, "listing credentials");
+        const json = await safeJson(res);
+        if (!json)
+            return err("Failed to parse credential list response");
+        const creds = json.data ?? [];
+        const lines = (Array.isArray(creds) ? creds : []).map((c) => `- ${c.name} (ID: ${c.id}, Type: ${c.type}, Created: ${c.createdAt ?? "N/A"})`);
+        return ok(`Found ${lines.length} credentials:\n${lines.join("\n")}`);
+    });
+}
+//# sourceMappingURL=credentials.js.map

package/build/tools/executions.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { ok, err, handleError, safeJson, } from "../types.js";
+import { n8nId, paginationCursor } from "../validation.js";
+export function registerExecutionTools(server, n8nFetch) {
+    // --- list_executions ---
+    server.tool("list_executions", "List n8n workflow executions with optional filters for workflow ID and status.", {
+        workflowId: n8nId.optional().describe("Filter by workflow ID"),
+        status: z.enum(["error", "success", "waiting"]).optional().describe("Filter by execution status"),
+        limit: z.number().int().positive().max(200).optional().default(20).describe("Max results (default 20)"),
+        cursor: paginationCursor,
+    }, async ({ workflowId, status, limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (workflowId)
+            params.set("workflowId", workflowId);
+        if (status)
+            params.set("status", status);
+        if (limit)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await n8nFetch(`/executions?${params}`);
+        if (!res.ok)
+            return handleError(res, "listing executions");
+        const json = await safeJson(res);
+        if (!json)
+            return err("Failed to parse execution list response");
+        const execs = json.data ?? [];
+        const lines = (Array.isArray(execs) ? execs : []).map((e) => `- #${e.id} | Workflow: ${e.workflowId} | Status: ${e.status} | Started: ${e.startedAt ?? "N/A"} | Finished: ${e.stoppedAt ?? "running"}`);
+        const next = json.nextCursor ? `\nNext cursor: ${json.nextCursor}` : "";
+        return ok(`Found ${lines.length} executions:\n${lines.join("\n")}${next}`);
+    });
+    // --- get_execution ---
+    server.tool("get_execution", "Get full details of an n8n execution including node results and error data.", {
+        executionId: n8nId.describe("ID of the execution"),
+    }, async ({ executionId }) => {
+        const res = await n8nFetch(`/executions/${executionId}`);
+        if (!res.ok)
+            return handleError(res, "fetching execution");
+        const exec = await safeJson(res);
+        if (!exec)
+            return err("Failed to parse execution response");
+        return ok(JSON.stringify(exec, null, 2));
+    });
+    // --- delete_execution ---
+    server.tool("delete_execution", "Delete an n8n execution record by ID.", { executionId: n8nId.describe("ID of the execution to delete") }, async ({ executionId }) => {
+        const res = await n8nFetch(`/executions/${executionId}`, { method: "DELETE" });
+        if (!res.ok)
+            return handleError(res, "deleting execution");
+        return ok(`Deleted execution ${executionId}`);
+    });
+}
+//# sourceMappingURL=executions.js.map

package/build/tools/tags.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { ok, err, handleError, safeJson, } from "../types.js";
+import { n8nId, paginationCursor } from "../validation.js";
+export function registerTagTools(server, n8nFetch) {
+    // --- list_tags ---
+    server.tool("list_tags", "List all n8n tags used for organizing workflows.", {
+        limit: z.number().int().positive().max(200).optional().default(50).describe("Max results"),
+        cursor: paginationCursor,
+    }, async ({ limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (limit)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await n8nFetch(`/tags?${params}`);
+        if (!res.ok)
+            return handleError(res, "listing tags");
+        const json = await safeJson(res);
+        if (!json)
+            return err("Failed to parse tag list response");
+        const tags = json.data ?? [];
+        const lines = (Array.isArray(tags) ? tags : []).map((t) => `- ${t.name} (ID: ${t.id})`);
+        return ok(`Found ${lines.length} tags:\n${lines.join("\n")}`);
+    });
+    // --- create_tag ---
+    server.tool("create_tag", "Create a new tag for organizing n8n workflows.", { name: z.string().describe("Tag name") }, async ({ name }) => {
+        const res = await n8nFetch("/tags", { method: "POST", body: JSON.stringify({ name }) });
+        if (!res.ok)
+            return handleError(res, "creating tag");
+        const tag = await safeJson(res);
+        if (!tag)
+            return err("Failed to parse create tag response");
+        return ok(`Created tag "${tag.name}" (ID: ${tag.id})`);
+    });
+    // --- update_tag ---
+    server.tool("update_tag", "Rename an existing n8n tag.", {
+        tagId: n8nId.describe("ID of the tag to update"),
+        name: z.string().describe("New tag name"),
+    }, async ({ tagId, name }) => {
+        const res = await n8nFetch(`/tags/${tagId}`, { method: "PUT", body: JSON.stringify({ name }) });
+        if (!res.ok)
+            return handleError(res, "updating tag");
+        const tag = await safeJson(res);
+        if (!tag)
+            return err("Failed to parse update tag response");
+        return ok(`Updated tag to "${tag.name}" (ID: ${tag.id})`);
+    });
+    // --- delete_tag ---
+    server.tool("delete_tag", "Delete an n8n tag by ID.", { tagId: n8nId.describe("ID of the tag to delete") }, async ({ tagId }) => {
+        const res = await n8nFetch(`/tags/${tagId}`, { method: "DELETE" });
+        if (!res.ok)
+            return handleError(res, "deleting tag");
+        return ok(`Deleted tag ${tagId}`);
+    });
+}
+//# sourceMappingURL=tags.js.map

package/build/tools/users.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { ok, err, handleError, safeJson, } from "../types.js";
+import { n8nId, paginationCursor } from "../validation.js";
+export function registerUserTools(server, n8nFetch) {
+    // --- list_users ---
+    server.tool("list_users", "List all n8n users with their roles and status.", {
+        limit: z.number().int().positive().max(200).optional().default(50).describe("Max results"),
+        cursor: paginationCursor,
+    }, async ({ limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (limit)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await n8nFetch(`/users?${params}`);
+        if (!res.ok)
+            return handleError(res, "listing users");
+        const json = await safeJson(res);
+        if (!json)
+            return err("Failed to parse user list response");
+        const users = json.data ?? [];
+        const lines = (Array.isArray(users) ? users : []).map((u) => `- ${u.firstName ?? ""} ${u.lastName ?? ""} (ID: ${u.id}, Email: ${u.email}, Role: ${u.role ?? "N/A"})`);
+        return ok(`Found ${lines.length} users:\n${lines.join("\n")}`);
+    });
+    // --- get_user ---
+    server.tool("get_user", "Get full details of an n8n user by ID.", {
+        userId: n8nId.describe("ID of the user"),
+    }, async ({ userId }) => {
+        const res = await n8nFetch(`/users/${userId}`);
+        if (!res.ok)
+            return handleError(res, "fetching user");
+        const user = await safeJson(res);
+        if (!user)
+            return err("Failed to parse user response");
+        return ok(JSON.stringify(user, null, 2));
+    });
+}
+//# sourceMappingURL=users.js.map

package/build/tools/variables.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { ok, err, handleError, safeJson, } from "../types.js";
+import { n8nId, paginationCursor } from "../validation.js";
+export function registerVariableTools(server, n8nFetch) {
+    // --- list_variables ---
+    server.tool("list_variables", "List all n8n environment variables (values are masked for security).", {
+        limit: z.number().int().positive().max(200).optional().default(50).describe("Max results"),
+        cursor: paginationCursor,
+    }, async ({ limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (limit)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await n8nFetch(`/variables?${params}`);
+        if (!res.ok)
+            return handleError(res, "listing variables");
+        const json = await safeJson(res);
+        if (!json)
+            return err("Failed to parse variable list response");
+        const vars = json.data ?? [];
+        const lines = (Array.isArray(vars) ? vars : []).map((v) => `- ${v.key} (ID: ${v.id})`);
+        return ok(`Found ${lines.length} variables:\n${lines.join("\n")}`);
+    });
+    // --- create_variable ---
+    server.tool("create_variable", "Create a new n8n environment variable (key-value pair).", {
+        key: z.string().describe("Variable key/name"),
+        value: z.string().describe("Variable value"),
+    }, async ({ key, value }) => {
+        const res = await n8nFetch("/variables", { method: "POST", body: JSON.stringify({ key, value }) });
+        if (!res.ok)
+            return handleError(res, "creating variable");
+        const v = await safeJson(res);
+        if (!v)
+            return err("Failed to parse create variable response");
+        return ok(`Created variable "${v.key}" (ID: ${v.id})`);
+    });
+    // --- update_variable ---
+    server.tool("update_variable", "Update an existing n8n environment variable.", {
+        variableId: n8nId.describe("ID of the variable to update"),
+        key: z.string().optional().describe("New key name"),
+        value: z.string().optional().describe("New value"),
+    }, async ({ variableId, key, value }) => {
+        const body = {};
+        if (key !== undefined)
+            body.key = key;
+        if (value !== undefined)
+            body.value = value;
+        const res = await n8nFetch(`/variables/${variableId}`, { method: "PUT", body: JSON.stringify(body) });
+        if (!res.ok)
+            return handleError(res, "updating variable");
+        const v = await safeJson(res);
+        if (!v)
+            return err("Failed to parse update variable response");
+        return ok(`Updated variable "${v.key}" (ID: ${v.id})`);
+    });
+    // --- delete_variable ---
+    server.tool("delete_variable", "Delete an n8n environment variable by ID.", { variableId: n8nId.describe("ID of the variable to delete") }, async ({ variableId }) => {
+        const res = await n8nFetch(`/variables/${variableId}`, { method: "DELETE" });
+        if (!res.ok)
+            return handleError(res, "deleting variable");
+        return ok(`Deleted variable ${variableId}`);
+    });
+}
+//# sourceMappingURL=variables.js.map

package/build/tools/workflows.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { ok, err, handleError, safeJson, } from "../types.js";
+import { n8nId, paginationCursor } from "../validation.js";
+const nodeSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    type: z.string(),
+    typeVersion: z.number(),
+    position: z.tuple([z.number(), z.number()]),
+    parameters: z.record(z.unknown()).optional().default({}),
+    onError: z.string().optional().describe("Error handling: 'continueRegularOutput' | 'continueErrorOutput' | 'stopWorkflow'"),
+    credentials: z.record(z.unknown()).optional().describe("Credential references for this node"),
+    webhookId: z.string().optional().describe("Webhook ID for trigger nodes"),
+});
+export function registerWorkflowTools(server, n8nFetch) {
+    // --- list_workflows ---
+    server.tool("list_workflows", "List all n8n workflows with optional name filter and pagination.", {
+        limit: z.number().int().positive().max(200).optional().default(50).describe("Max results (default 50)"),
+        cursor: paginationCursor,
+    }, async ({ limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (limit)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await n8nFetch(`/workflows?${params}`);
+        if (!res.ok)
+            return handleError(res, "listing workflows");
+        const json = await safeJson(res);
+        if (!json)
+            return err("Failed to parse workflow list response");
+        const workflows = json.data ?? [];
+        const lines = (Array.isArray(workflows) ? workflows : []).map((w) => `- ${w.name} (ID: ${w.id}, Active: ${w.active})`);
+        const next = json.nextCursor ? `\nNext cursor: ${json.nextCursor}` : "";
+        return ok(`Found ${lines.length} workflows:\n${lines.join("\n")}${next}`);
+    });
+    // --- get_workflow ---
+    server.tool("get_workflow", "Get full details of an n8n workflow by ID, including nodes, connections, and settings.", {
+        workflowId: n8nId.describe("ID of the workflow"),
+    }, async ({ workflowId }) => {
+        const res = await n8nFetch(`/workflows/${workflowId}`);
+        if (!res.ok)
+            return handleError(res, "fetching workflow");
+        const w = await safeJson(res);
+        if (!w)
+            return err("Failed to parse workflow response");
+        return ok(JSON.stringify(w, null, 2));
+    });
+    // --- create_workflow ---
+    server.tool("create_workflow", "Create a new n8n workflow. Provide a name and optionally nodes/connections. Defaults to a Manual Trigger node if no nodes given.", {
+        name: z.string().describe("Workflow name"),
+        nodes: z.array(nodeSchema).optional().describe("Array of workflow nodes (defaults to Manual Trigger)"),
+        connections: z.record(z.unknown()).optional().default({}).describe("Node connections mapping"),
+        settings: z.record(z.unknown()).optional().default({}).describe("Workflow settings"),
+    }, async ({ name, nodes, connections, settings }) => {
+        const defaultNodes = [
+            {
+                id: "trigger-1",
+                name: "Manual Trigger",
+                type: "n8n-nodes-base.manualTrigger",
+                typeVersion: 1,
+                position: [0, 0],
+                parameters: {},
+            },
+        ];
+        const body = { name, nodes: nodes ?? defaultNodes, connections: connections ?? {}, settings: settings ?? {} };
+        const res = await n8nFetch("/workflows", { method: "POST", body: JSON.stringify(body) });
+        if (!res.ok)
+            return handleError(res, "creating workflow");
+        const w = await safeJson(res);
+        if (!w)
+            return err("Failed to parse create workflow response");
+        return ok(`Created workflow "${w.name}" (ID: ${w.id}, Active: ${w.active})`);
+    });
+    // --- update_workflow ---
+    server.tool("update_workflow", "Update an existing n8n workflow. Provide the workflow ID and any fields to change.", {
+        workflowId: n8nId.describe("ID of the workflow to update"),
+        name: z.string().optional().describe("New workflow name"),
+        nodes: z.array(nodeSchema).optional().describe("Updated nodes array"),
+        connections: z.record(z.unknown()).optional().describe("Updated connections"),
+        settings: z.record(z.unknown()).optional().describe("Updated settings"),
+    }, async ({ workflowId, name, nodes, connections, settings }) => {
+        const getRes = await n8nFetch(`/workflows/${workflowId}`);
+        if (!getRes.ok)
+            return handleError(getRes, "fetching workflow for update");
+        const current = await safeJson(getRes);
+        if (!current)
+            return err("Failed to parse current workflow for update");
+        const body = {
+            name: name ?? current.name,
+            nodes: nodes ?? current.nodes,
+            connections: connections ?? current.connections,
+            settings: settings ?? current.settings,
+        };
+        const res = await n8nFetch(`/workflows/${workflowId}`, { method: "PUT", body: JSON.stringify(body) });
+        if (!res.ok)
+            return handleError(res, "updating workflow");
+        const w = await safeJson(res);
+        if (!w)
+            return err("Failed to parse update workflow response");
+        return ok(`Updated workflow "${w.name}" (ID: ${w.id})`);
+    });
+    // --- delete_workflow ---
+    server.tool("delete_workflow", "Delete an n8n workflow by ID. This is irreversible.", { workflowId: n8nId.describe("ID of the workflow to delete") }, async ({ workflowId }) => {
+        const res = await n8nFetch(`/workflows/${workflowId}`, { method: "DELETE" });
+        if (!res.ok)
+            return handleError(res, "deleting workflow");
+        return ok(`Deleted workflow ${workflowId}`);
+    });
+    // --- activate_workflow ---
+    server.tool("activate_workflow", "Activate an n8n workflow so it runs on its configured triggers.", { workflowId: n8nId.describe("ID of the workflow to activate") }, async ({ workflowId }) => {
+        const res = await n8nFetch(`/workflows/${workflowId}/activate`, { method: "POST" });
+        if (!res.ok)
+            return handleError(res, "activating workflow");
+        return ok(`Activated workflow ${workflowId}`);
+    });
+    // --- deactivate_workflow ---
+    server.tool("deactivate_workflow", "Deactivate an n8n workflow so it stops running on triggers.", { workflowId: n8nId.describe("ID of the workflow to deactivate") }, async ({ workflowId }) => {
+        const res = await n8nFetch(`/workflows/${workflowId}/deactivate`, { method: "POST" });
+        if (!res.ok)
+            return handleError(res, "deactivating workflow");
+        return ok(`Deactivated workflow ${workflowId}`);
+    });
+    // --- execute_workflow ---
+    server.tool("execute_workflow", "Execute an n8n workflow immediately and return the execution ID. The workflow runs asynchronously.", { workflowId: n8nId.describe("ID of the workflow to execute") }, async ({ workflowId }) => {
+        const res = await n8nFetch(`/workflows/${workflowId}/execute`, {
+            method: "POST",
+            body: JSON.stringify({}),
+        });
+        if (!res.ok)
+            return handleError(res, "executing workflow");
+        const result = await safeJson(res);
+        if (!result)
+            return err("Failed to parse execution response");
+        return ok(`Execution started for workflow ${workflowId} (Execution ID: ${result.executionId})`);
+    });
+}
+//# sourceMappingURL=workflows.js.map

package/build/types.js

@@ -0,0 +1,21 @@
+// --- MCP response helpers ---
+export function ok(msg) {
+    return { content: [{ type: "text", text: msg }] };
+}
+export function err(msg) {
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+export async function handleError(res, action) {
+    const status = res.status;
+    const statusText = res.statusText || "Unknown error";
+    return err(`Error ${action}: HTTP ${status} ${statusText}`);
+}
+export async function safeJson(res) {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=types.js.map

package/build/validation.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+/**
+ * Schema for n8n resource IDs.
+ * n8n uses numeric IDs (integers as strings) for all resources.
+ * Prevents path traversal attacks (e.g. "../admin").
+ */
+export const n8nId = z
+    .string()
+    .regex(/^\d+$/, "ID must be a numeric string (e.g. '123')")
+    .describe("Numeric resource ID");
+/**
+ * Schema for pagination cursors.
+ * Cursors are alphanumeric base64-like strings from the n8n API.
+ */
+export const paginationCursor = z
+    .string()
+    .regex(/^[a-zA-Z0-9+/=_-]+$/, "Invalid cursor format")
+    .optional()
+    .describe("Pagination cursor from previous response");
+//# sourceMappingURL=validation.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@thecodesaiyan/tcs-n8n-mcp",
+  "version": "1.0.2",
+  "description": "MCP server for n8n workflow automation. Manage workflows, executions, tags, variables, credentials and users via the Model Context Protocol.",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "tcs-n8n-mcp": "build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "n8n",
+    "workflow",
+    "automation",
+    "ai",
+    "llm",
+    "claude",
+    "mcp-server"
+  ],
+  "author": "ntatschner",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ntatschner/tcs-n8n-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ntatschner/tcs-n8n-mcp/issues"
+  },
+  "homepage": "https://github.com/ntatschner/tcs-n8n-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  }
+}