Skip to main content
Version: DEV

启动 RAGFlow MCP 服务器

从源代码或通过 Docker 启动 MCP 服务器。

RAGFlow 模型上下文协议（MCP）服务器设计为独立组件，用于补充 RAGFlow 服务器。请注意，MCP 服务器必须与正常运行的 RAGFlow 服务器一起运行。

MCP 服务器可以以自托管模式（默认）或主机模式启动：

  • 自托管模式： 在自托管模式下启动 MCP 服务器时，您必须提供 API 密钥来验证 MCP 服务器与 RAGFlow 服务器的身份。在此模式下，MCP 服务器只能访问 RAGFlow 服务器上指定租户的知识库（知识库）。
  • 主机模式： 在主机模式下，每个 MCP 客户端都可以访问 RAGFlow 服务器上自己的知识库。但是，每个客户端请求都必须包含有效的 API 密钥来验证客户端与 RAGFlow 服务器的身份。

建立连接后，MCP 服务器以 MCP HTTP+SSE（服务器发送事件）模式与其客户端通信，实时单向推送 RAGFlow 服务器的响应到其客户端。

前置条件​

  1. 确保 RAGFlow 已升级到 v0.18.0 或更高版本。
  2. 准备好您的 RAGFlow API 密钥。请参阅获取 RAGFlow API 密钥。
信息

如果您希望在不升级 RAGFlow 的情况下试用我们的 MCP 服务器，社区贡献者 yiminghub2024 👏 在此处分享了他们推荐的步骤在不升级 RAGFlow 的情况下启动 MCP 服务器。

启动 MCP 服务器​

您可以从源代码或通过 Docker 启动 MCP 服务器。

从源代码启动​

  1. 确保 RAGFlow 服务器 v0.18.0+ 正常运行。
  2. 启动 MCP 服务器：
# 启动 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

# 要启动 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：正在运行的 RAGFlow 服务器的地址。
  • mode：启动模式。
    • self-host：（默认）自托管模式。
    • host：主机模式。
  • api_key：在自托管模式下需要，用于验证 MCP 服务器与 RAGFlow 服务器的身份。有关获取 API 密钥的说明，请参阅此处。

传输协议​

RAGFlow MCP 服务器支持两种传输协议：传统 SSE 传输（在 /sse 提供服务），于 2024 年 11 月 5 日引入并于 2025 年 3 月 26 日弃用，以及可流式 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 服务器：

  1. 导航到 docker/docker-compose.yml。
  2. 取消注释 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 艺术确认成功启动：

  ragflow-server  | Starting MCP Server on 0.0.0.0:9382 with base URL http://127.0.0.1:9380...
  ragflow-server  | Starting 1 task executor(s) on host 'dd0b5e07e76f'...
  ragflow-server  | 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'}
  ragflow-server  | 
  ragflow-server  | __  __  ____ ____       ____  _____ ______     _______ ____
  ragflow-server  | |  \/  |/ ___|  _ \     / ___|| ____|  _ \ \   / / ____|  _ \
  ragflow-server  | | |\/| | |   | |_) |    \___ \|  _| | |_) \ \ / /|  _| | |_) |
  ragflow-server  | | |  | | |___|  __/      ___) | |___|  _ < \ V / | |___|  _ <
  ragflow-server  | |_|  |_|\____|_|        |____/|_____|_| \_\ \_/  |_____|_| \_\
  ragflow-server  |     
  ragflow-server  | MCP launch mode: self-host
  ragflow-server  | MCP host: 0.0.0.0
  ragflow-server  | MCP port: 9382
  ragflow-server  | MCP base_url: http://127.0.0.1:9380
  ragflow-server  | INFO:     Started server process [26]
  ragflow-server  | INFO:     Waiting for application startup.
  ragflow-server  | INFO:     Application startup complete.
  ragflow-server  | INFO:     Uvicorn running on http://0.0.0.0:9382 (Press CTRL+C to quit)
  ragflow-server  | 2025-04-18 15:41:20,469 INFO     27 found 0 gpus
  ragflow-server  | 2025-04-18 15:41:23,263 INFO     27 init database on cluster mode successfully
  ragflow-server  | 2025-04-18 15:41:25,318 INFO     27 load_model /ragflow/rag/res/deepdoc/det.onnx uses CPU
  ragflow-server  | 2025-04-18 15:41:25,367 INFO     27 load_model /ragflow/rag/res/deepdoc/rec.onnx uses CPU
  ragflow-server  |         ____   ___    ______ ______ __               
  ragflow-server  |        / __ \ /   |  / ____// ____// /____  _      __
  ragflow-server  |       / /_/ // /| | / / __ / /_   / // __ \| | /| / /
  ragflow-server  |      / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ / 
  ragflow-server  |     /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/                             
  ragflow-server  | 
  ragflow-server  |     
  ragflow-server  | 2025-04-18 15:41:29,088 INFO     27 RAGFlow version: v0.18.0-285-gb2c299fa full
  ragflow-server  | 2025-04-18 15:41:29,088 INFO     27 project base: /ragflow
  ragflow-server  | 2025-04-18 15:41:29,088 INFO     27 Current configs, from /ragflow/conf/service_conf.yaml:
  ragflow-server  |  ragflow: {'host': '0.0.0.0', 'http_port': 9380}
  ...
  ragflow-server  |  * Running on all addresses (0.0.0.0)
  ragflow-server  |  * Running on http://127.0.0.1:9380
  ragflow-server  |  * Running on http://172.19.0.6:9380
  ragflow-server  |   ______           __      ______                     __            
  ragflow-server  |  /_  __/___ ______/ /__   / ____/  _____  _______  __/ /_____  _____
  ragflow-server  |   / / / __ `/ ___/ //_/  / __/ | |/_/ _ \/ ___/ / / / __/ __ \/ ___/
  ragflow-server  |  / / / /_/ (__  ) ,<    / /____>  </  __/ /__/ /_/ / /_/ /_/ / /    
  ragflow-server  | /_/  \__,_/____/_/|_|  /_____/_/|_|\___/\___/\__,_/\__/\____/_/                               
  ragflow-server  |     
  ragflow-server  | 2025-04-18 15:41:34,501 INFO     32 TaskExecutor: RAGFlow version: v0.18.0-285-gb2c299fa full
  ragflow-server  | 2025-04-18 15:41:34,501 INFO     32 Use Elasticsearch http://es01:9200 as the doc engine.
  ...

在不升级 RAGFlow 的情况下启动 MCP 服务器​

致谢

此部分由我们的社区贡献者 yiminghub2024 贡献。👏

  1. 准备所有 MCP 特定文件和目录。 i. 将 mcp/ 目录复制到您的本地工作目录。 ii. 本地复制 docker/docker-compose.yml。 iii. 本地复制 docker/entrypoint.sh。 iv. 使用 uv 安装所需的依赖项：
    • 运行 uv add mcp 或
    • 本地复制 pyproject.toml 并运行 uv sync --python 3.10 --all-extras。
  2. 编辑 docker-compose.yml 以启用 MCP（默认禁用）。
  3. 启动 MCP 服务器：
docker compose -f docker-compose.yml up -d

检查 MCP 服务器状态​

运行以下命令检查 RAGFlow 服务器和 MCP 服务器的日志：

docker logs ragflow-server

安全考虑​

由于 MCP 技术仍处于早期阶段，尚未建立身份验证或授权的官方最佳实践，RAGFlow 目前使用 API 密钥 来验证前面描述的操作的身份。但是，在公共环境中，这种临时解决方案可能会使您的 MCP 服务器面临潜在的网络攻击。因此，在运行本地 SSE 服务器时，建议仅绑定到 localhost（127.0.0.1）而不是所有接口（0.0.0.0）。

有关更多指导，请参阅官方 MCP 文档。

常见问题​

何时使用 API 密钥进行身份验证？​

API 密钥的使用取决于您的 MCP 服务器的运行模式。

  • 自托管模式（默认）： 在自托管模式下启动 MCP 服务器时，您应该在启动时提供 API 密钥来验证其与 RAGFlow 服务器的身份：
    • 如果从源代码启动，请在命令中包含 API 密钥。
    • 如果从 Docker 启动，请在 docker/docker-compose.yml 中更新 API 密钥。
  • 主机模式： 如果您的 RAGFlow MCP 服务器在主机模式下工作，请在客户端请求的 headers 中包含 API 密钥来验证您的客户端与 RAGFlow 服务器的身份。示例可在此处找到。