启动 RAGFlow MCP 服务端 (Launch RAGFlow MCP server)
从源码或通过 Docker 启动一个模型上下文协议 (Model Context Protocol, MCP) 服务端。
RAGFlow 模型上下文协议 (Model Context Protocol, MCP) 服务端是一个独立的组件，用以补充 RAGFlow 服务端。请注意，MCP 服务端必须配合正常运行的 RAGFlow 服务端一起工作。
MCP 服务端可以以自托管模式（Self-host Mode，默认值）或托管模式（Host Mode）启动：
- 自托管模式 (Self-host Mode)：在此模式下启动 MCP 服务端时，您必须提供一个 API 密钥 (API Key)，用于对 MCP 服务端在 RAGFlow 服务端上进行身份验证。在此模式下，MCP 服务端仅能访问 RAGFlow 服务端上指定租户的知识库/数据集（Dataset）。
- 托管模式 (Host Mode)：在此模式下，每个 MCP 客户端都可以访问自己在 RAGFlow 服务端上的知识库/数据集。但是，每个客户端请求中都必须包含一个有效的 API 密钥，以便对该客户端在 RAGFlow 服务端上进行身份验证。
连接建立后，MCP 服务端将以 MCP HTTP+SSE（服务发送事件，Server-Sent Events）模式与其客户端通信，实时单向地将来自 RAGFlow 服务端的响应推送给其客户端。
前提条件
- 确保已将 RAGFlow 升级到 v0.18.0 或更高版本。
- 准备好您的 RAGFlow API 密钥。有关步骤，请参阅获取 RAGFlow API 密钥。
信息
如果您想在不升级 RAGFlow 的情况下尝试我们的 MCP 服务端，社区贡献者 yiminghub2024 👏 在此处分享了他们的推荐步骤。
启动 MCP 服务端
您可以从源码或通过 Docker 来启动 MCP 服务端。
从源码启动
- 确保 RAGFlow 服务端（v0.18.0 或更高版本）正在正常运行。
- 启动 MCP 服务端：
# 要在自托管（self-host）模式下启动 MCP 服务端，运行以下任一命令：
uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --api-key=ragflow-xxxxx
# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=self-host --api-key=ragflow-xxxxx
# 要在托管（host）模式下启动 MCP 服务端，请运行以下命令：
# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=host
其中：
host：MCP 服务端的主机地址。port：MCP 服务端的监听端口。base_url：正在运行 of RAGFlow 服务端的地址。mode：启动模式。self-host：（默认）自托管模式。host：托管模式。
api_key：在自托管模式下为必需项，用于对 MCP 服务端在 RAGFlow 服务端上进行身份验证。获取 API 密钥的步骤请参见此处。
传输协议 (Transports)
RAGFlow MCP 服务端支持两种传输协议：于 2024 年 11 月 5 日引入并于 2025 年 3 月 26 日弃用的传统 SSE 传输（服务路径为 /sse），以及可流式传输的 HTTP 传输（服务路径为 /mcp）。默认情况下已启用传统 SSE 传输和带有 JSON 响应的可流式 HTTP 传输。要禁用这两种传输协议中的任何一个，可以使用 --no-transport-sse-enabled 或 --no-transport-streamable-http-enabled 标志。要禁用可流式 HTTP 传输的 JSON 响应，请使用 --no-json-response 标志。
从 Docker 启动
1. 启用 MCP 服务端
MCP 服务端被设计为 RAGFlow 服务端的补充性可选组件，默认被禁用。要启用 MCP 服务端：
- 前往 docker/docker-compose.yml。
- 取消对
services.ragflow.command部分的注释，如下所示：
services:
ragflow:
...
image: ${RAGFLOW_IMAGE}
# 配置 MCP 服务端的示例：
command:
- --enable-mcpserver
- --mcp-host=0.0.0.0
- --mcp-port=9382
- --mcp-base-url=http://127.0.0.1:9380
- --mcp-script-path=/ragflow/mcp/server/server.py
- --mcp-mode=self-host
- --mcp-host-api-key=ragflow-xxxxxxx
# RAGFlow MCP 服务端的可选传输标志。
# 如果您将 mcp-mode 设置为 host，您必须添加 --no-transport-streamable-http-enabled 标志，因为托管模式下目前尚不支持可流式 HTTP 传输。
# 默认情况下已启用传统 SSE 传输和带有 JSON 响应的可流式 HTTP 传输。
# 若要禁用特定的传输或禁用可流式 HTTP 传输的 JSON 响应，请使用相应的标志：
# - --no-transport-sse-enabled # 禁用传统 SSE 接口（/sse）
# - --no-transport-streamable-http-enabled # 禁用可流式 HTTP 传输（服务路径为 /mcp）
# - --no-json-response # 禁用可流式 HTTP 传输的 JSON 响应
其中：
mcp-host：MCP 服务端的主机地址。mcp-port：MCP 服务端的监听端口。mcp-base-url：正在运行的 RAGFlow 服务端的地址。mcp-script-path：MCP 服务端主脚本的文件路径。mcp-mode：启动模式。self-host：（默认）自托管模式。host：托管模式。
mcp-host-api-key：在自托管模式下为必需项，用于对 MCP 服务端在 RAGFlow 服务端上进行身份验证。获取 API 密钥的步骤请参见此处。
提示
如果您将 mcp-mode 设置为 host，您必须添加 --no-transport-streamable-http-enabled 标志，因为托管模式下目前尚不支持可流式 HTTP 传输。
2. 启动带 MCP 服务的 RAGFlow 服务端
运行 docker compose -f docker-compose.yml up 启动 RAGFlow 服务端以及 MCP 服务端。
以下字符画（ASCII Art）及控制台输出确认启动成功：
docker-ragflow-cpu-1 | Starting MCP Server on 0.0.0.0:9382 with base URL http://127.0.0.1:9380...
docker-ragflow-cpu-1 | Starting 1 task executor(s) on host 'dd0b5e07e76f'...
docker-ragflow-cpu-1 | 2025-04-18 15:41:18,816 INFO 27 ragflow_server log path: /ragflow/logs/ragflow_server.log, log levels: {'peewee': 'WARNING', 'pdfminer': 'WARNING', 'root': 'INFO'}
docker-ragflow-cpu-1 |
docker-ragflow-cpu-1 | __ __ ____ ____ ____ _____ ______ _______ ____
docker-ragflow-cpu-1 | | \/ |/ ___| _ \ / ___|| ____| _ \ \ / / ____| _ \
docker-ragflow-cpu-1 | | |\/| | | | |_) | \___ \| _| | |_) \ \ / /| _| | |_) |
docker-ragflow-cpu-1 | | | | | |___| __/ ___) | |___| _ < \ V / | |___| _ <
docker-ragflow-cpu-1 | |_| |_|\____|_| |____/|_____|_| \_\ \_/ |_____|_| \_\
docker-ragflow-cpu-1 |
docker-ragflow-cpu-1 | MCP launch mode: self-host
docker-ragflow-cpu-1 | MCP host: 0.0.0.0
docker-ragflow-cpu-1 | MCP port: 9382
docker-ragflow-cpu-1 | MCP base_url: http://127.0.0.1:9380
docker-ragflow-cpu-1 | INFO: Started server process [26]
docker-ragflow-cpu-1 | INFO: Waiting for application startup.
docker-ragflow-cpu-1 | INFO: Application startup complete.
docker-ragflow-cpu-1 | INFO: Uvicorn running on http://0.0.0.0:9382 (Press CTRL+C to quit)
docker-ragflow-cpu-1 | 2025-04-18 15:41:20,469 INFO 27 found 0 gpus
docker-ragflow-cpu-1 | 2025-04-18 15:41:23,263 INFO 27 init database on cluster mode successfully
docker-ragflow-cpu-1 | 2025-04-18 15:41:25,318 INFO 27 load_model /ragflow/rag/res/deepdoc/det.onnx uses CPU
docker-ragflow-cpu-1 | 2025-04-18 15:41:25,367 INFO 27 load_model /ragflow/rag/res/deepdoc/rec.onnx uses CPU
docker-ragflow-cpu-1 | ____ ___ ______ ______ __
docker-ragflow-cpu-1 | / __ \ / | / ____// ____// /____ _ __
docker-ragflow-cpu-1 | / /_/ // /| | / / __ / /_ / // __ \| | /| / /
docker-ragflow-cpu-1 | / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ /
docker-ragflow-cpu-1 | /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/
docker-ragflow-cpu-1 |
docker-ragflow-cpu-1 |
docker-ragflow-cpu-1 | 2025-04-18 15:41:29,088 INFO 27 RAGFlow version: v0.18.0-285-gb2c299fa full
docker-ragflow-cpu-1 | 2025-04-18 15:41:29,088 INFO 27 project base: /ragflow
docker-ragflow-cpu-1 | 2025-04-18 15:41:29,088 INFO 27 Current configs, from /ragflow/conf/service_conf.yaml:
docker-ragflow-cpu-1 | ragflow: {'host': '0.0.0.0', 'http_port': 9380}
...
docker-ragflow-cpu-1 | * Running on all addresses (0.0.0.0)
docker-ragflow-cpu-1 | * Running on http://127.0.0.1:9380
docker-ragflow-cpu-1 | * Running on http://172.19.0.6:9380
docker-ragflow-cpu-1 | ______ __ ______ __
docker-ragflow-cpu-1 | /_ __/___ ______/ /__ / ____/ _____ _______ __/ /_____ _____
docker-ragflow-cpu-1 | / / / __ `/ ___/ //_/ / __/ | |/_/ _ \/ ___/ / / / __/ __ \/ ___/
docker-ragflow-cpu-1 | / / / /_/ (__ ) ,< / /____> </ __/ /__/ /_/ / /_/ /_/ / /
docker-ragflow-cpu-1 | /_/ \__,_/____/_/|_| /_____/_/|_|\___/\___/\__,_/\__/\____/_/
docker-ragflow-cpu-1 |
docker-ragflow-cpu-1 | 2025-04-18 15:41:34,501 INFO 32 TaskExecutor: RAGFlow version: v0.18.0-285-gb2c299fa full
docker-ragflow-cpu-1 | 2025-04-18 15:41:34,501 INFO 32 Use Elasticsearch http://es01:9200 as the doc engine.
...
在不升级 RAGFlow 的情况下启动 MCP 服务端
鸣谢
本章节由我们的社区贡献者 yiminghub2024 贡献。👏
- 准备所有 MCP 特定的文件和目录。
i. 将 mcp/ 目录复制到本地的工作目录中。
ii. 将 docker/docker-compose.yml 复制到本地。
iii. 将 docker/entrypoint.sh 复制到本地。
iv. 使用uv安装必需的依赖项：- 运行
uv add mcp，或者 - 将 pyproject.toml 复制到本地并运行
uv sync --python 3.12。
- 运行
- 编辑 docker-compose.yml 以启用 MCP（默认情况下被禁用）。
- 启动 MCP 服务端：
docker compose -f docker-compose.yml up -d
检查 MCP 服务端状态
运行以下命令以查看 RAGFlow 服务端和 MCP 服务端的日志：
docker logs docker-ragflow-cpu-1
安全考量
由于 MCP 技术仍处于早期阶段，官方尚未建立统一的身份验证（Authentication）或授权（Authorization）最佳实践，因此 RAGFlow 目前使用 API 密钥来验证上述操作的身份。然而，在公开网络环境中，这种权宜之计可能会使您的 MCP 服务端暴露于潜在的网络攻击风险中。因此，在本地运行 SSE 服务器时，强烈建议仅绑定到本地环回地址（127.0.0.1），而非所有网卡接口（0.0.0.0）。
有关更多指南，请参阅 MCP 官方安全文档。
常见问题解答
什么时候需要使用 API 密钥进行身份验证？
是否使用 API 密钥取决于您的 MCP 服务端的运行模式：
- 自托管模式 (Self-host Mode)（默认值）：
在自托管模式下启动 MCP 服务端时，您应当在启动时提供一个 API 密钥，以便在 RAGFlow 服务端进行身份验证：- 如果从源码启动，请在启动命令中包含 API 密钥。
- 如果从 Docker 启动，请在 docker/docker-compose.yml 中更新 API 密钥。
- 托管模式 (Host Mode)：
如果您的 RAGFlow MCP 服务端在托管模式下运行，请在客户端请求的headers（请求头）中包含 API 密钥，以便该客户端在 RAGFlow 服务端进行身份验证。示例代码可参见此处。