内容
# Node-RED MCP 服务器
<div align="center">
[](https://badge.fury.io/js/node-red-contrib-mcp-tools)
[](https://snyk.io/test/npm/node-red-contrib-mcp-tools/1.1.3)
</div>
通过模型上下文协议（MCP）将 Node-RED 连接到大型语言模型（LLM），以实现智能 AI 工作流。
[](https://railway.com/deploy/node-red-mcp)
> **🚀 即刻部署 Railway 模板** - 配置了 MCP（模型上下文协议）的 Node-RED，用于 LLM 集成
## 📋 项目描述
该项目最初设计采用基于 Docker 的设置，使用两个容器：Node-RED 和一个负责运行 MCP（模型上下文协议）服务器的 mcp-host。这种架构使得 Node-RED 流程能够通过专用的 MCP 层与 LLM 进行交互。
随着 `node-red-contrib-mcp-tools` 版本 **2.2.0** 的发布，架构得到了显著简化。
只需安装 `node-red-contrib-mcp-tools` 组件即可启用可流式传输的 HTTP 传输 - 无需额外的容器或服务。
您可以运行本地和远程 MCP 服务器。
远程 MCP 示例：
MCP 服务器 URL：
```bash
https://mcp.exa.ai/mcp
```
Bearer Token：
前往 https://dashboard.exa.ai/api-keys 并生成一个 API 密钥
```
a98e0***************************...
```
[🔗 在 smithery.ai 上查找其他 MCP](https://smithery.ai)
## 🚀 在 Railway 上部署
[](https://railway.com/deploy/node-red-mcp)
### 工作原理
存储库包含一个现成的 Railway 配置：
| 文件 | 用途 |
|------|---------|
| `Dockerfile.railway` | 从存储库根目录构建镜像 - 复制流程、MCP 服务器和配置脚本 |
| `railway.toml` | 告诉 Railway 使用哪个 Dockerfile 并设置启动命令 |
| `docker-init/user-provision.js` | 每次容器启动时运行 - 对管理员密码进行哈希处理并将其写入 `settings.js` |
**构建流程：**
```
存储库根目录（构建上下文）
├── node-red-docker/node_red_data → /data （流程、设置、节点）
├── mcp-server/v1 → /data/mcp-server/v1 （MCP 服务器 + gdrive）
└── docker-init/user-provision.js → /data/user-provision.js
```
**启动命令（来自 `railway.toml`）：**
```sh
cd /data && node user-provision.js && node-red --userDir /data
```
`user-provision.js` 读取 `ADMIN_PASSWORD` 环境变量（或生成一个随机变量），对 bcrypt 进行哈希处理，然后将其写入 `settings.js` 中，然后启动 Node-RED。
### 部署步骤
1. Fork 或将此存储库连接到 Railway
2. 在 Railway 服务设置中 → **构建**：
- **根目录**：留空
- **Dockerfile 路径**：`/Dockerfile.railway`
3. 在 Railway 仪表板中设置环境变量：
- `ADMIN_PASSWORD` - 您选择的 Node-RED 管理员密码
- `OPENAI_API_KEY` - 可选，用于 OpenAI LLM 节点
4. 部署 - Railway 将自动构建和启动。
### 获取管理员密码
如果您没有设置 `ADMIN_PASSWORD`，则会在首次启动时生成一个随机密码。在 Railway 仪表板中找到它：
1. Railway 仪表板 → 您的服务 → **部署** 标签页
2. 点击最新部署 → **日志**
3. 查找区块：
```
============================================================
NODE-RED 管理员凭证
============================================================
用户名：admin
密码：<生成的密码>
============================================================
```
### 持久化卷（一次性设置）
流程和凭证存储在 `/data` 中。要在重新部署时保留它们：
1. Railway 仪表板 → 您的服务 → **卷** 标签页
2. 添加卷 → 挂载路径：`/data`
> 如果没有卷，每次重新部署时，流程都会重置为存储库的默认值。
---
## ▶️ 如何运行
通过 docker compose 运行项目的步骤：
1. 克隆此存储库：
```bash
git clone https://github.com/moises-paschoalick/node-red-mcp-server
cd node-red-mcp-server
docker compose up -d
```
2. 在此处打开项目：http://localhost:1899/
3. 安装 mcp-tools 节点
要执行此操作，我们需要有 mcp-tools 节点，请在 Node-RED UI 中安装 node-red-contrib-mcp-tools。
选项 -> 管理面板
安装 node-red-contrib-mcp-tools
[安装图像]
[node-red-contrib-mcp-tools 链接](https://github.com/node-red-contrib-mcp-tools)
4. 使用您的 OpenAI API 密钥配置组件
[组件图像]
## 🔐 环境变量和安全性
### OpenAI API 密钥配置
`mcp-tools` 组件支持多种配置您的 OpenAI API 密钥的方式：
#### 选项 1：直接输入（不推荐用于生产环境）
- 直接在组件配置中输入您的 API 密钥
- 字段将被遮蔽为密码以确保安全
- **⚠️ 警告**：此方法会使您的 API 密钥在 Node-RED 流程中暴露
#### 选项 2：环境变量（推荐）
- 使用格式：`{{OPENAI_API_KEY}}`
- 组件将自动检测并使用系统环境变量
- **✅ 安全**：API 密钥不会存储在流程中
#### 选项 3：Node-RED 凭证
- 在 Node-RED 的凭证管理系统存储您的 API 密钥
- 生产环境中最安全的选项
### MCP 服务器环境变量
组件可以通过多种方式将环境变量传递给您的 MCP 服务器：
#### 选项 1：JSON 配置
```json
{
"id_field": "您的电子表格 ID",
"GOOGLE_CLIENT_ID": "您的 Google 客户端 ID",
"GOOGLE_CLIENT_SECRET": "您的 Google 客户端密钥",
"GOOGLE_REFRESH_TOKEN": "您的 Google 刷新令牌"
}
```
#### 选项 2：环境变量引用
- 使用格式：`{{ENV_MCP_VARIABLES}}`
- 组件将从系统环境变量加载
- **✅ 安全**：凭证不会存储在流程中
#### 选项 3：外部文件
- 在组件中指定 `.env` 文件路径
- 组件将自动读取并解析文件
### 提示中的动态变量替换
组件使用 `{{VAR_NAME}}` 格式自动替换提示中的环境变量：
#### 示例用法：
**原始提示：**
```
更新字段 {{id_field}} 范围 Sheet1!A1 值 更新的行 2
```
**替换后：**
```
更新字段 1t6w************************************yWGU 范围 Sheet1!A1 值 更新的行 2
```
#### 支持的变量源：
1. **MCP 服务器环境变量**（优先级最高）
2. **系统环境变量**（备用）
3. **组件配置**（优先级最低）
### 安全最佳实践
1. **永远不要提交真正的凭证** 到版本控制
2. **在生产部署中使用环境变量**
3. **将敏感数据存储在 `.env` 文件中**（不提交）
4. **尽可能使用 Node-RED 凭证** 存储 API 密钥
5. **定期轮换** 您的 API 密钥和令牌
### 示例环境配置
在项目根目录创建 `.env` 文件：
```bash
# OpenAI API 密钥
OPENAI_API_KEY=sk-您的实际-api-key-此处
# MCP 服务器环境变量（JSON 字符串）
ENV_MCP_VARIABLES={"id_field":"您的电子表格 ID","GOOGLE_CLIENT_ID":"您的 Google 客户端 ID","GOOGLE_CLIENT_SECRET":"您的 Google 客户端密钥","GOOGLE_REFRESH_TOKEN":"您的 Google 刷新令牌"}
# 替代：单个变量
# id_field=您的电子表格 ID
# GOOGLE_CLIENT_ID=您的 Google 客户端 ID
# GOOGLE_CLIENT_SECRET=您的 Google 客户端密钥
# GOOGLE_REFRESH_TOKEN=您的 Google 刷新令牌
```
**⚠️ 重要**：将 `.env` 添加到您的 `.gitignore` 文件中，以防止意外提交。
### 实际示例：Google Sheets 集成
以下是使用 `mcp-tools` 组件与 Google Sheets 操作结合使用环境变量的完整示例：
#### 1. 环境配置
```bash
# .env 文件
OPENAI_API_KEY=sk-您的-openai-key
ENV_MCP_VARIABLES={"id_field":"您的电子表格 ID","GOOGLE_CLIENT_ID":"您的客户端 ID","GOOGLE_CLIENT_SECRET":"您的客户端密钥","GOOGLE_REFRESH_TOKEN":"您的刷新令牌"}
```
#### 2. 组件配置
- **MCP 主机 URL：** `http://mcp-host:3000`
- **OpenAI API 密钥：** `{{OPENAI_API_KEY}}`
- **MCP 服务器命令：** `node`
- **MCP 服务器参数：** `../mcp-server-demo/gdrive-mcp/build/index.js`
- **MCP 服务器环境变量：** `{{ENV_MCP_VARIABLES}}`
#### 3. 消息负载
```json
{
"payload": "更新字段 {{id_field}} 范围 Sheet1!A1 值 更新的行 2"
}
```
#### 4. 结果
组件将自动：
1. 从 `{{ENV_MCP_VARIABLES}}` 加载环境变量
2. 用实际的电子表格 ID 替换 `{{id_field}}`
3. 将处理的提示发送到 MCP 服务器
4. 执行 Google Sheets 操作
## 🧱 容器结构
- **`mcp-host`**
组件构建为 Node.js，充当 Node-RED（通过 `mcp-tools` 组件）和 MCP 服务器之间的桥梁。
它负责在 `mcp-client`（LLM 模型）和 `mcp-server`（了解工具实现）之间进行通信。
- **`mcp-server-demo`**（Node-RED）
包含已配置为使用 `mcp-tools` 组件与 `mcp-host` 通信的 Node-RED 环境。 它是一个使用 NodeJS 构建的 MCP 服务器示例，用于测试和验证环境是否功能正常。
> **重要**：在 Node-RED 中的 **mcp-tools** 组件中，您需要将 MCP 主机 URL 配置为：
> ```
> http://mcp-host:3000
> ```
---
## 📦 组件
- **`mcp-host`**
- 接收来自 Node-RED 的 `mcp-tools` 调用
- 重定向请求到 `mcp-client`
- 将结果转发到 `mcp-server`（本地或远程）
- **`mcp-client`**
- 处理与语言模型（LLM）的通信
- 目前使用 OpenAI 的 `gpt-4o` 模型
- 可以在未来修改为使用其他模型（例如 Claude、Gemini、LLaMA）
- **`mcp-server-demo`**
- 一个功能性的 MCP 服务器本地示例
- 包含可以由模型调用的“工具”，例如：
- **Hello Tool**：响应 “Hello World”
- **Local Time**：返回本地服务器时间
- **Weather Tool**：通过 `wttr.in` 查询 São Paulo 的当前天气
---
### 先决条件
- Docker
- Docker Compose
### 验证 mcp-host 完整性的端点
http://localhost:3000/health
## 架构
<p align="center">
<img src="assets/architecture-mcp-tools.png" alt="MCP 工具架构" />
</p>
### 组件
#### 1. **mcp-host** (Web 服务器)
- **位置：** `/mcp-host/`
- **功能：** Express.js 服务器，负责协调通信
- **端口：** 3000（可配置）
- **端点：**
- `POST /execute` - 执行提示
- `GET /health` - 服务器状态
- `GET /tools` - 列出可用工具
- `POST /disconnect` - 断开会话
#### 2. **mcp-client** (MCP 客户端)
- **位置：** `/mcp-client/`
- **功能：** 管理与 MCP 服务器和 OpenAI 的连接
- **功能：**
- 自动连接/断开连接
- 会话管理
- MCP 工具转换为 OpenAI 格式
- 使用工具调用执行提示
#### 3. **mcp-server** (MCP 服务器)
- **位置：** `/mcp-server/`
- **功能：** MCP 服务器实现与工具和资源
- **包含的工具：**
- Hello Tool（示例）
- Users Tool（外部 API）
- Textract Tool（图像分析）
#### 4. **node-red-mcp-component** (Node-RED 组件)
- **位置：** `/node-red-mcp-component/`
- **功能：** 可自定义的 Node-RED 节点
- **配置：**
- MCP 主机 URL
- OpenAI API 密钥（支持 `{{ENV_VAR}}` 格式）
- MCP 服务器命令
- MCP 服务器参数
- MCP 服务器环境变量（支持 `{{ENV_VAR}}` 格式）
- 外部环境文件路径
- 会话 ID
- 超时
- **功能：**
- **动态环境变量替换** 在提示中
- **智能输入字段类型** （密钥的密码，环境变量的文本）
- **多个凭证源** （直接，环境变量，凭证）
- **自动 JSON 解析** 环境变量
- **会话管理** 以重用连接
## API 端点
### POST /execute
通过 MCP 代理执行提示。
**请求体：**
```json
{
"prompt": "显示 Hello World 消息",
"apiKey": "sk-您的密钥",
"serverCommand": "node",
"serverArgs": ["../mcp-server/build/index.js"],
"sessionId": "default"
}
```
**响应：**
```json
{
"success": true,
"response": "Hello, World! 这是工具响应！",
"toolsUsed": [...],
"messages": [...]
}
```
### GET /health
检查服务器状态。
**响应：**
```json
{
"status": "ok",
"timestamp": "2025-06-11T23:32:04.612Z",
"activeClients": 0
}
```
### GET /tools
列出可用的工具。
**查询参数：**
- `apiKey` - OpenAI API 密钥
- `serverCommand` - MCP 服务器命令
- `serverArgs` - MCP 服务器参数
## 安装和配置（无 Docker）
### 1. 准备组件
```bash
# 安装 mcp-server 依赖项
cd mcp-server/v1
npm install
npm run build
cd mcp-server/v1/gdrive-mcp
npm install
npm run build
# 安装 mcp-client 依赖项
cd ../mcp-client
npm install
npm run build
# 安装 mcp-host 依赖项
cd ../mcp-host
npm install
```
### 2. 启动 MCP 主机
```bash
cd mcp-host
npm start
```
服务器将在 3000 端口运行。
## 🤝 贡献
1. **Fork** 项目
2. **创建分支** 您的功能（`git checkout -b feature/AmazingFeature`）
3. **提交** 您的更改（`git commit -m 'Add some AmazingFeature'`）
4. **推送** 到分支（`git push origin feature/AmazingFeature`）
5. **打开拉取请求**
## 📄 许可证
该项目使用 MIT 许可证 - 参见 [LICENSE](LICENSE) 文件了解详情。
## 🆘 支持
### 帮助渠道
- **🐛 问题：** [GitHub 问题](https://github.com/moises-paschoalick/node-red-mcp-server/issues)
- **💬 讨论：** [Github 讨论](https://github.com/moises-paschoalick/node-red-mcp-server/discussions)
### 有用的资源
- [Node-RED 文档](https://nodered.org/docs/)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [Railway 文档](https://docs.railway.app/)
- [OpenAI API 文档](https://platform.openai.com/docs/)
## 🙏 致谢
- [Node-RED](https://nodered.org/) - 视觉编程平台
- [Railway](https://railway.app/) - 部署平台
- [OpenAI](https://openai.com/) - 语言模型
- [MCP 社区](https://modelcontextprotocol.io/) - MCP 协议
---
**⭐ 如果此模板有帮助，请考虑给存储库加星！**
