跳到主要内容

启动RAGFlow MCP服务器

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

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

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

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

一旦建立连接，MCP服务器将以HTTP+SSE（Server-Sent Events）单向推送的方式与其客户端通信，在实时情况下将来自RAGFlow服务器的响应推送给其客户端。

先决条件​

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

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

启动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：在自托管模式下，必须提供API密钥以验证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启动​

# 若要在自托管模式下启动MCP服务器，请执行以下命令：
docker run -d --name mcp-server \
    -e RAGFLOW_API_KEY=ragflow-xxxxx \
    -p 9382:9380/tcp \
    -p 57612:57612/udp \
    ghcr.io/crab-team/ragflow/mcpc:v0.20

# 若要在主机模式下启动MCP服务器，请执行以下命令：
docker run -d --name mcp-server-host \
    -e RAGFLOW_API_KEY=ragflow-xxxxx \
    -p 9382:9380/tcp \
    ghcr.io/crab-team/ragflow/mcpc:v0.20

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  | 正在0.0.0.0:9382上启动MCP Server，基础URL为http://127.0.0.1:9380...
  ragflow-server  | 在主机'dd0b5e07e76f'上启动1个任务执行器...
  ragflow-server  | 2025-04-18 15:41:18,816 INFO     27 RAGFlow日志路径：/ragflow/logs/ragflow_server.log，日志级别：{'peewee': 'WARNING', 'pdfminer': 'WARNING', 'root': 'INFO'}
  ragflow-server  | 
  ragflow-server  | __  __  ____ ____       ____  _____ ______     _______ ____
  ragflow-server  | |  \/  |/ ___|  _ \     / ___|| ____|  _ \ \   / / ____|  _ \
  ragflow-server  | | |\/| | |   | |_) |    \___ \|  _| | |_) \ \ / /|  _| | |_) |
  ragflow-server  | | |  | | |___|  __/      ___) | |___|  _ < \ V / | |___|  _ <
  ragflow-server  | |_|  |_|\____|_|        |____/|_____|_| \_\ \_/  |_____|_| \_\
  ragflow-server  |     
  ragflow-server  | MCP启动模式：自托管
  ragflow-server  | MCP主机：0.0.0.0
  ragflow-server  | MCP端口：9382
  ragflow-server  | MCP基础URL：http://127.0.0.1:9380
  ragflow-server  | INFO:     启动服务器进程[26]
  ragflow-server  | INFO:     等待应用程序启动。
  ragflow-server  | INFO:     应用程序启动完成。
  ragflow-server  | INFO:     Uvicorn正在http://0.0.0.0:9382上运行（按CTRL+C退出）
  ragflow-server  | 2025-04-18 15:41:20,469 INFO     27 检测到0个GPU
  ragflow-server  | 2025-04-18 15:41:23,263 INFO     27 集群模式下初始化数据库成功
  ragflow-server  | 2025-04-18 15:41:25,318 INFO     27 加载模型/ragflow/rag/res/deepdoc/det.onnx使用CPU
  ragflow-server  | 2025-04-18 15:41:25,367 INFO     27 加载模型/ragflow/rag/res/deepdoc/rec.onnx使用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版本：v0.18.0-285-gb2c299fa 全功能版
  ragflow-server  | 2025-04-18 15:41:29,088 INFO     27 工程基础路径：/ragflow
  ragflow-server  | 2025-04-18 15:41:29,088 INFO     27 当前配置，从/ragflow/conf/service_conf.yaml：
  ragflow-server  |  ragflow: {'host': '0.0.0.0', 'http_port': 9380}
  ...
  ragflow-server  |  * 在所有地址（0.0.0.0）上运行
  ragflow-server  |  * 在http://127.0.0.1:9380上运行
  ragflow-server  |  * 在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版本：v0.18.0-285-gb2c299fa 全功能版
  ragflow-server  | 2025-04-18 15:41:34,501 INFO     32 使用Elasticsearch http://es01:9200作为文档引擎。
  ...

在不升级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服务器时，建议只绑定到本地主机（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服务器进行身份验证。示例请参见此处。