nodered-mcp 1.0.0

package/README.md

@@ -0,0 +1,24 @@
+# Node-RED MCP
+
+MCP server for Node-RED: flows, nodes. Works with any instance.
+
+## Setup
+
+```bash
+export NODERED_URL=http://localhost:1880
+export NODERED_TOKEN=token_if_adminauth_on
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `list_flows`: Flow tabs with ids.
+- `get_flow`: Node count and type breakdown.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. Everything stays on your network.

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+export declare class NodeRedError extends Error {
+}
+type Raw = Record<string, any>;
+export interface Flow {
+    id: string;
+    label?: string;
+    nodes: number;
+    disabled?: boolean;
+}
+export declare function listFlows(): Promise<Flow[]>;
+export declare function getFlow(id: string): Promise<Raw[]>;
+export declare function formatFlow(id: string, nodes: Raw[]): string;
+export {};

package/dist/api.js

@@ -0,0 +1,55 @@
+/**
+ * Node-RED Admin HTTP API client. Points at any instance via NODERED_URL
+ * (default http://localhost:1880). If adminAuth is on, set NODERED_TOKEN
+ * (Bearer) — get one by logging into the editor once.
+ * Docs: https://nodered.org/docs/api/admin/methods/
+ */
+const BASE = (process.env.NODERED_URL ?? "http://localhost:1880").replace(/\/+$/, "");
+export class NodeRedError extends Error {
+}
+function headers() {
+    const h = { "User-Agent": "nodered-mcp/1.0", Accept: "application/json" };
+    if (process.env.NODERED_TOKEN)
+        h.Authorization = `Bearer ${process.env.NODERED_TOKEN}`;
+    return h;
+}
+async function getJson(path) {
+    let res;
+    try {
+        res = await fetch(`${BASE}${path}`, {
+            headers: headers(),
+            signal: AbortSignal.timeout(20000),
+        });
+    }
+    catch {
+        throw new NodeRedError(`Node-RED at ${BASE} is unreachable. Set NODERED_URL.`);
+    }
+    if (res.status === 401 || res.status === 403)
+        throw new NodeRedError("Node-RED refused (401/403). Set NODERED_TOKEN.");
+    if (res.status === 404)
+        throw new NodeRedError("Not found.");
+    if (!res.ok)
+        throw new NodeRedError(`Node-RED error ${res.status}`);
+    return (await res.json());
+}
+export async function listFlows() {
+    const rows = await getJson("/flows");
+    return rows
+        .filter((f) => f.type === "tab")
+        .map((f) => ({ id: String(f.id), label: f.label, nodes: 0, disabled: f.disabled }));
+}
+export async function getFlow(id) {
+    if (!id.trim())
+        throw new NodeRedError("Flow id is empty.");
+    const nodes = await getJson(`/flow/${encodeURIComponent(id.trim())}`);
+    return Array.isArray(nodes) ? nodes : [];
+}
+export function formatFlow(id, nodes) {
+    if (nodes.length === 0)
+        return `Flow ${id}: no nodes.`;
+    const kinds = {};
+    for (const n of nodes)
+        kinds[String(n.type ?? "?")] = (kinds[String(n.type ?? "?")] ?? 0) + 1;
+    const top = Object.entries(kinds).sort((a, b) => b[1] - a[1]).slice(0, 8);
+    return [`Flow ${id} (${nodes.length} nodes):`, ...top.map(([k, v]) => `- ${k} x${v}`)].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { formatFlow, getFlow, listFlows, NodeRedError } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "nodered-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("list_flows", {
+        title: "List flows",
+        description: "Node-RED flow tabs with ids and labels. Set NODERED_URL for non-default hosts.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        try {
+            const rows = await listFlows();
+            if (rows.length === 0)
+                return text("No flows.");
+            return text(rows.map((f, i) => `${i + 1}. [${f.id}] ${f.label ?? "(unnamed)"}${f.disabled ? " (disabled)" : ""}`).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_flow", {
+        title: "Get flow",
+        description: "One flow: node count plus node-type breakdown.",
+        inputSchema: z.object({
+            id: z.string().describe("Flow tab id (use list_flows)"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ id }) => {
+        try {
+            return text(formatFlow(id, await getFlow(id)));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof NodeRedError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "nodered-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Node-RED: flows, nodes. Works with any instance.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/nodered-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "nodered-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "node-red",
+    "flows",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}