node-red-object-action-mcp

Expose your Node-RED flows as MCP (Model Context Protocol) servers. Declare an object (e.g. office lights) with free-text actions (turn on, turn off, …) and readable values (status, brightness), and an AI agent speaking MCP can call them as tools — driving your flow and reading values back out of it.

The server speaks JSON-RPC 2.0 over the Streamable HTTP transport (MCP protocol 2025-06-18) and is mounted on Node-RED's own runtime HTTP server, so no extra port or process is needed.

Nodes

Related MCP server: nr-mcp

How it works

                                   ┌─────────────────────────────┐
  MCP client ──HTTP POST /mcp──▶   │  object-action-mcp-endpoint │
  (agent)    ◀──JSON-RPC result    └─────────────────────────────┘
                                         │ tools/call        ▲
                                         ▼                   │ resolve
             ┌──────────────┐      ┌───────────┐      ┌──────────────┐
             │  object/read │──msg─▶│ your flow │──msg─▶│ mcp response │
             └──────────────┘      └───────────┘      └──────────────┘

• Actions (object node) can be configured per action to either:

  • return an instant ack (fire-and-forget — the configured ack text is returned at once), or

  • wait for a response node (the call is held open until a response node returns a result).

• Reads (object read node) always wait for a response node to supply the value.

• Parameters: actions and reads can declare typed parameters (string / number / boolean, optional/required). They become the tool's MCP inputSchema, and the call arguments arrive on msg.payload.

The emitted msg carries object, action/read, tool, and an opaque _oamcp correlation handle. Pass _oamcp through unchanged so the response node can match the value back to the right call. The response node returns msg.payload (a string is sent as text; an object is also returned as structuredContent); set msg.isError = true to return it as a tool error.

Install

From your Node-RED user directory (~/.node-red):

npm install node-red-object-action-mcp

or, for local development, install from a checkout:

cd ~/.node-red
npm install /path/to/node-red-object-action-mcp

Restart Node-RED. The nodes appear under the mcp palette category.

Quick start

1. Drag an object node onto a flow, add an endpoint config (path /mcp), set the object to office lights, and add actions turn on and turn off (instant ack).

2. Wire each action output to a debug (or your device logic).

3. Drag an object read node on the same endpoint, object office lights, value status; wire it through a function that sets msg.payload into an mcp response node.

4. Deploy.

An importable version of this flow is in examples/office-lights.json.

Try it with curl

# initialize
curl -s http://localhost:1880/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# list tools
curl -s http://localhost:1880/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# call an action
curl -s http://localhost:1880/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"office_lights_turn_on","arguments":{}}}'

# read a value
curl -s http://localhost:1880/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"office_lights_status","arguments":{}}}'

Try it with the MCP Inspector

npx @modelcontextprotocol/inspector

Choose the Streamable HTTP transport and connect to http://localhost:1880/mcp.

Tool names

Tool names are derived from the object and action/value names, lowercased with non [a-z0-9_-] characters replaced by _ (e.g. office lights + turn on → office_lights_turn_on). Duplicate names on one endpoint are rejected (the later node shows a red status and a warning in the log).

Authentication

Each endpoint can optionally require a bearer token (set Auth = Bearer token on the config node). Clients then send Authorization: Bearer <token>. You can also rely on Node-RED's own httpNodeAuth/httpNodeMiddleware settings for the whole HTTP server.

Note: MCP endpoints are served on Node-RED's runtime HTTP server. Expose them only on trusted networks, or put them behind TLS and the bearer token (or a reverse proxy).

Notes & limitations

• Implements the tools surface only (initialize, tools/list, tools/call, ping). No resources, prompts, or server-initiated streaming; GET returns 405 by design.

• Sessions are lenient: an Mcp-Session-Id is issued on initialize but not required on later requests, so the server works statelessly.

• JSON-RPC batching is intentionally unsupported (it was removed in MCP 2025-06-18).

• Zero runtime dependencies.

Development

npm install
npm test

License

MIT © Sam Machin