node-red-contrib-mcp-server 1.1.5
A comprehensive Node-RED wrapper for Model Context Protocol (MCP) servers providing standardized AI agent tool interfaces, server lifecycle management, real-time communication capabilities, and visual MCP server creation
node-red-contrib-mcp-server
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.
Features
- 🚀 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
Installation
From npm (when published)
cd ~/.node-red
npm install node-red-contrib-mcp-server
Manual Installation
cd ~/.node-red
git clone <repository-url> node_modules/node-red-contrib-mcp-server
cd node_modules/node-red-contrib-mcp-server
npm install
Local Development
cd /path/to/node-red-contrib-mcp-server
npm link
cd ~/.node-red
npm link node-red-contrib-mcp-server
Quick Start with Examples
The package includes ready-to-use example flows to get you started quickly:
📁 External MCP Server Example
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
🏗️ Flow-Based MCP Server Example
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
How to Import Examples
- In Node-RED: Menu (☰) → Import
- Select "select a file to import"
- Choose an example JSON file from the
examples/
directory - Click "Import" and deploy
For detailed setup instructions, see examples/README.md
.
Nodes
🖥️ MCP Server Node
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 serverstop
: Stop the serverrestart
: Restart the serverstatus
: Get current status
Output Topics:
stdout
: Server standard outputstderr
: Server error outputstarted
: Server startup eventexit
: Server exit event
🔗 MCP Client Node
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 connectiondisconnect
: Close connectionrequest
: Send MCP requeststatus
: Get connection status
Output Topics:
connected
: Connection establishedresponse
: MCP response receivedmessage
: General server messageerror
: Error occurredraw
: Unparsed message data
⚙️ MCP Tool Node
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:
- Message-specific properties (
msg.description
,msg.project
, etc.) msg.payload.params
objectmsg.payload
(if object without method)- 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
Examples
Basic MCP Server Setup
// 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
Client Connection and Tool Call
// 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;
Direct Tool Invocation
// 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;
Server Lifecycle Management
// 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;
Omnispindle Integration
This package includes built-in support for the Omnispindle MCP server:
Available Tools
add_todo_tool
- Create new todoslist_todos_by_status_tool
- List todos by statusupdate_todo_tool
- Update existing todosdelete_todo_tool
- Delete todosmark_todo_complete_tool
- Mark todos completelist_project_todos_tool
- List project todosquery_todos_tool
- Search/query todos
Quick Setup
- Use "Load Omnispindle Preset" buttons in node configurations
- Automatically configures for local Omnispindle server
- Sets appropriate connection types and parameters
Advanced Usage
Health Monitoring Flow
// 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: {}};
}
Dynamic Tool Discovery
// Function node to get available tools:
msg.topic = "request";
msg.payload = {
method: "tools/list",
params: {}
};
return msg;
// Process response to populate UI or routing
Connection Failover
// Function node for client failover:
if (msg.topic === "error") {
// Try backup server
msg.topic = "connect";
msg.payload = {serverUrl: "http://backup:8000"};
return msg;
}
API Endpoints
The package exposes additional HTTP endpoints:
GET /mcp-servers
- List running MCP serversGET /mcp-tools/:serverUrl
- Get available tools from server
Requirements
System Requirements
- Node.js 16.0.0 or higher
- Node-RED 1.0.0 or higher
MCP Server Requirements
- 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
Dependencies
axios
- HTTP clientws
- WebSocket supporteventsource
- Server-Sent Eventsuuid
- Unique ID generationnode-cache
- Server instance caching
Troubleshooting
Server Won't Start
- Check server path exists and is executable
- Verify Python/Node.js environment
- Check port availability
- Review server arguments syntax
Connection Issues
- Verify server is running and accessible
- Check firewall settings
- Confirm correct URL and port
- Test with simple HTTP health check
Tool Calls Fail
- Ensure server supports the requested tool
- Validate parameter JSON syntax
- Check server logs for errors
- Verify authentication if required
Performance Issues
- Adjust health check intervals
- Configure appropriate timeouts
- Use connection pooling for high volume
- Monitor server resource usage
Development
Contributing
- Fork the repository
- Create feature branch
- Add tests for new functionality
- Submit pull request
Testing
npm test
Building
npm run build
License
MIT License - see LICENSE file for details.
Changelog
v1.0.0
- Initial release
- MCP Server, Client, and Tool nodes
- Omnispindle integration
- Multi-protocol support
- Health monitoring
- Auto-restart capabilities
Support
- 📖 Documentation
- 🐛 Issues
- 💬 Discussions
Related Projects
- Omnispindle - FastMCP-based todo management system
- FastMCP - Model Context Protocol server framework
- Node-RED - Flow-based programming for the Internet of Things