A comprehensive Node-RED contribution package for Model Context Protocol (MCP) server integration. This package provides nodes for running MCP servers, connecting to them as clients, and invoking specific MCP tools directly from Node-RED flows.

• 🚀 MCP Server Management: Start, stop, and monitor MCP servers directly from Node-RED
• 🔗 Multi-Protocol Support: HTTP, Server-Sent Events (SSE), and WebSocket connections
• 🛠️ Tool Integration: Direct invocation of MCP tools with parameter mapping
• 💾 Health Monitoring: Automatic health checks and restart capabilities
• 📊 Real-time Communication: Live streaming of server output and events
• 🎯 Omnispindle Integration: Built-in presets for the Omnispindle MCP server

cd ~/.node-red
npm install node-red-contrib-mcp-server

cd ~/.node-red
git clone <repository-url> node_modules/node-red-contrib-mcp-server
cd node_modules/node-red-contrib-mcp-server
npm install

cd /path/to/node-red-contrib-mcp-server
npm link
cd ~/.node-red
npm link node-red-contrib-mcp-server

The package includes ready-to-use example flows to get you started quickly:

Demonstrates connecting to external MCP servers like Omnispindle:

• File: examples/external-mcp-server-example.json
• Shows: SSE connection, tool discovery, direct tool calls
• Setup: Import → Deploy → Watch debug output

Demonstrates creating MCP servers entirely within Node-RED:

• File: examples/flow-based-mcp-server-example.json
• Shows: Custom tools, visual server creation, self-testing
• Setup: Import → Deploy → Server runs on port 8001

1. In Node-RED: Menu (☰) → Import
2. Select "select a file to import"
3. Choose an example JSON file from the examples/ directory
4. Click "Import" and deploy

For detailed setup instructions, see examples/README.md.

Manages the lifecycle of MCP server processes.

Key Features:

• Start/stop MCP servers (Python, Node.js, or custom commands)
• Health monitoring with automatic restarts
• Real-time output streaming
• Environment variable configuration
• Port management

Configuration:

• Server Type: Python, Node.js, or Custom
• Server Path: Path to server script/executable
• Server Arguments: Command line arguments
• Port: Server port number
• Auto Start: Start with Node-RED
• Health Checks: Monitor server health
• Restart Policy: Automatic restart on failure

Input Commands:

• start: Start the server
• stop: Stop the server
• restart: Restart the server
• status: Get current status

Output Topics:

• stdout: Server standard output
• stderr: Server error output
• started: Server startup event
• exit: Server exit event

Connects to and communicates with MCP servers.

Key Features:

• Multiple connection types (HTTP, SSE, WebSocket)
• Automatic reconnection
• Request/response handling
• Real-time event streaming
• Connection pooling

Configuration:

• Server URL: MCP server endpoint
• Connection Type: HTTP, SSE, or WebSocket
• Auto Connect: Connect on startup
• Reconnect: Auto-reconnect on disconnect
• Timeout: Request timeout

Input Commands:

• connect: Establish connection
• disconnect: Close connection
• request: Send MCP request
• status: Get connection status

Output Topics:

• connected: Connection established
• response: MCP response received
• message: General server message
• error: Error occurred
• raw: Unparsed message data

Simplified interface for invoking specific MCP tools.

Key Features:

• Predefined tool configurations
• Parameter mapping and overrides
• Output formatting options
• Dynamic tool discovery
• Omnispindle tool presets

Configuration:

• Server URL: MCP server endpoint
• Tool Name: MCP tool to invoke
• Default Parameters: JSON parameter defaults
• Output Mode: Result formatting
• Timeout: Request timeout

Parameter Override Priority:

1. Message-specific properties (msg.description, msg.project, etc.)
2. msg.payload.params object
3. msg.payload (if object without method)
4. Default parameters from configuration

Output Modes:

• Result Only: Extract result from MCP response
• Full Response: Complete MCP JSON-RPC response
• Custom: Preserve original message, add response

// Use MCP Server node with these settings:
// Server Type: Python
// Server Path: src/Omnispindle/__init__.py
// Server Args: --host 0.0.0.0 --port 8000
// Auto Start: true

// Connect to MCP server
msg.topic = "connect";
return msg;

// Later: Call a tool
msg.topic = "request";
msg.payload = {
    method: "add_todo_tool",
    params: {
        description: "Implement MCP integration",
        project: "NodeRED"
    }
};
return msg;

// Configure MCP Tool node for "add_todo_tool"
// Then send:
msg.description = "New task from Node-RED";
msg.project = "MyProject";
msg.priority = "High";
return msg;

// Start server
msg.topic = "start";
return msg;

// Monitor output
// Connect to stdout output and process server logs

// Stop server when done
msg.topic = "stop";
return msg;

This package includes built-in support for the Omnispindle MCP server:

• add_todo_tool - Create new todos
• list_todos_by_status_tool - List todos by status
• update_todo_tool - Update existing todos
• delete_todo_tool - Delete todos
• mark_todo_complete_tool - Mark todos complete
• list_project_todos_tool - List project todos
• query_todos_tool - Search/query todos

1. Use "Load Omnispindle Preset" buttons in node configurations
2. Automatically configures for local Omnispindle server
3. Sets appropriate connection types and parameters

// MCP Server node output → Function node:
if (msg.topic === "stdout" && msg.payload.includes("error")) {
    // Alert on errors
    return {topic: "alert", payload: "Server error detected"};
}
if (msg.topic === "exit" && msg.payload.code !== 0) {
    // Server crashed
    return {topic: "restart", payload: {}};
}

// Function node to get available tools:
msg.topic = "request";
msg.payload = {
    method: "tools/list",
    params: {}
};
return msg;

// Process response to populate UI or routing

// Function node for client failover:
if (msg.topic === "error") {
    // Try backup server
    msg.topic = "connect";
    msg.payload = {serverUrl: "http://backup:8000"};
    return msg;
}

The package exposes additional HTTP endpoints:

• GET /mcp-servers - List running MCP servers
• GET /mcp-tools/:serverUrl - Get available tools from server

• Node.js 16.0.0 or higher
• Node-RED 1.0.0 or higher

• Python servers: Python 3.8+ with required packages
• Node.js servers: Node.js 16+ with required packages
• Custom servers: Executable in PATH or full path specified

• axios - HTTP client
• ws - WebSocket support
• eventsource - Server-Sent Events
• uuid - Unique ID generation
• node-cache - Server instance caching

• Check server path exists and is executable
• Verify Python/Node.js environment
• Check port availability
• Review server arguments syntax

• Verify server is running and accessible
• Check firewall settings
• Confirm correct URL and port
• Test with simple HTTP health check

• Ensure server supports the requested tool
• Validate parameter JSON syntax
• Check server logs for errors
• Verify authentication if required

• Adjust health check intervals
• Configure appropriate timeouts
• Use connection pooling for high volume
• Monitor server resource usage

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Submit pull request

npm test

npm run build

MIT License - see LICENSE file for details.

• Initial release
• MCP Server, Client, and Tool nodes
• Omnispindle integration
• Multi-protocol support
• Health monitoring
• Auto-restart capabilities

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

• Omnispindle - FastMCP-based todo management system
• FastMCP - Model Context Protocol server framework
• Node-RED - Flow-based programming for the Internet of Things