node-red-contrib-mcp-tools 3.2.1

Node-RED component for executing MCP (Model Context Protocol)

npm install node-red-contrib-mcp-tools

node-red-contrib-mcp-tools

A Node-RED node for connecting to Model Context Protocol (MCP) servers and executing AI prompts with tool use — no extra containers or services required.

Supports OpenAI, Anthropic, Google Gemini, and OpenRouter as LLM providers. Connects to MCP servers via Stdio (local process) or Streamable HTTP (remote URL).

Installation

Via Palette Manager (recommended)

1. Open Node-RED → hamburger menu → Manage Palette
2. Go to the Install tab
3. Search for node-red-contrib-mcp-tools and click Install

Via terminal

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

Restart Node-RED after installation. The node appears in the function category.

Quick Start

Streamable HTTP (zero setup)

The simplest way to use the node — connect to a remote MCP server with just a URL:

1. Drag an mcp-tools node into your flow
2. Set Transport Type → Streamable HTTP
3. Enter the MCP Server URL, e.g. https://mcp.exa.ai/mcp
4. Enter your Bearer Token if the server requires auth, e.g. {{EXA_API_KEY}}
5. Set your LLM Provider and API Key
6. Connect an inject node with a prompt string and deploy

Stdio (local process)

For running a local MCP server process inside the container:

1. Set Transport Type → Stdio
2. Configure MCP Servers with the command and args:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/data/mcp-server-demo/build/index.js"]
    }
  }
}

Node Configuration

LLM Provider

Default models per provider:

Transport Type

Streamable HTTP — remote MCP server via URL:

Stdio — local MCP server process:

Other fields

{{VAR_NAME}} Environment Variable Substitution

Any field that accepts a {{VAR_NAME}} token will be substituted at runtime:

Priority: MCP Server Envs field > container environment (process.env)

Supported fields:

• API Key → {{OPENAI_API_KEY}}
• Bearer Token → {{EXA_API_KEY}}
• args[] entries → {{MY_SERVER_PATH}}
• Prompt text → {{MY_VALUE}}
• MCP Server Environment Variables → {{ENV_MCP_VARIABLES}} (must resolve to a JSON object string)

MCP Servers Configuration (Stdio mode)

Single local server

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/data/mcp-server-demo/build/index.js"]
    }
  }
}

Note: npx-based servers automatically get a 300s connection timeout to allow package download on first run.

Multiple servers

When multiple servers are configured, the node automatically selects the best one based on keyword matching in the prompt.

{
  "mcpServers": {
    "search": {
      "command": "node",
      "args": ["/data/search-server/index.js"]
    },
    "database": {
      "command": "node",
      "args": ["/data/db-server/index.js"]
    }
  }
}

Remote HTTP server (in Stdio config)

{
  "mcpServers": {
    "remote": {
      "url": "https://mcp.example.com/mcp",
      "token": "{{MY_TOKEN}}"
    }
  }
}

Inputs

Outputs

Example Flow

[
  {
    "id": "inject1",
    "type": "inject",
    "name": "Ask",
    "props": [{ "p": "payload", "v": "Search for the latest news about MCP protocol", "vt": "str" }],
    "x": 100, "y": 100,
    "wires": [["mcp1"]]
  },
  {
    "id": "mcp1",
    "type": "mcp-tools",
    "name": "MCP Tools",
    "provider": "openai",
    "model": "",
    "apiKey": "{{OPENAI_API_KEY}}",
    "transportType": "http",
    "mcpServerUrl": "https://mcp.exa.ai/mcp",
    "mcpServerToken": "{{EXA_API_KEY}}",
    "prompt": "",
    "timeout": 30000,
    "x": 300, "y": 100,
    "wires": [["debug1"]]
  },
  {
    "id": "debug1",
    "type": "debug",
    "name": "Result",
    "complete": "true",
    "x": 500, "y": 100,
    "wires": []
  }
]

Docker Setup

A ready-to-use Docker Compose setup is available at node-red-mcp-server.

services:
  node-red:
    image: nodered/node-red:4.0.0
    ports:
      - "1880:1880"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - EXA_API_KEY=${EXA_API_KEY}

Troubleshooting

invalid_token error on HTTP transport

• Check that your Bearer Token field contains the correct env var, e.g. {{EXA_API_KEY}}
• Verify the env var is set in your container environment

spawn ENOENT error

• The MCP server command was not found. Check the command and args paths.
• For servers inside Docker, paths must be absolute container paths (e.g. /data/...)

npx timeout

• First run downloads the package — this can take 30–60s
• The node auto-sets 300s timeout for npx commands

Provider API key not found

• Use {{OPENAI_API_KEY}} (or the relevant provider env var) in the API Key field
• Or set the env var directly in the container

License

LGPL-3.0-or-later

You may use this node freely in your Node-RED flows, including in commercial and proprietary projects. However, any modifications to this node's source code must be released under the same LGPL license and contributed back to the project.