RAG-Anything MCP Server

RAG-Anything 的独立 FastMCP 服务器项目。该服务器通过 MCP 暴露文档解析、摄取、查询、多模态查询以及轻量级图谱检查工具。

快速开始

在当前目录中运行：

python3 -m venv .venv
source .venv/bin/activate
python scripts/install.py --dev
raganything-mcp configure
raganything-mcp serve

python scripts/install.py --dev 会自动检测本机是否有可用 NVIDIA GPU：检测到 GPU 时安装 GPU 版本解析依赖；未检测到 GPU 时安装 CPU 版本解析依赖，避免在无 GPU 机器上下载 CUDA/cuDNN 大包。

如需排错，也可以手动强制安装目标：

python scripts/install.py --dev --cpu
python scripts/install.py --dev --gpu

raganything-mcp configure 会创建本地 .env 文件。raganything-mcp serve 会为你的 MCP 客户端启动 stdio MCP 服务器。

模型配置层

这里有两个独立的模型层：

• 你的智能体客户端模型在连接 MCP 的客户端中配置，例如 OpenClaw 或 Claude Code。

• 此 MCP 服务器的 .env 会配置 RAG-Anything 内部用于 LLM 调用、嵌入以及视觉/多模态处理的模型。

更改客户端模型不会改变 RAG-Anything 内部的嵌入、解析或视觉设置。请通过此服务器的 .env 配置这些设置。

配置

运行：

raganything-mcp configure

该向导会写入 .env 设置，包括：

• LLM 提供商、基础 URL、模型和 API 密钥

• 嵌入提供商、基础 URL、模型、维度和 API 密钥

• 视觉提供商、基础 URL、模型和 API 密钥

• LightRAG 向量存储和图谱存储后端

• 解析器、解析方法、解析 backend、模型下载策略、解析超时、工作目录、输出目录、多模态处理标志和可选多模态处理超时

LLM、嵌入和视觉提供商可以不同。例如，你可以使用一个提供商进行聊天，另一个提供商生成嵌入，并使用单独的支持视觉的模型进行多模态处理。

存储后端

默认存储仍保持 LightRAG 本地文件模式：

LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage
LIGHTRAG_GRAPH_STORAGE=NetworkXStorage

如需使用 Milvus Lite 保存向量、Neo4j 保存知识图谱，可设置：

LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage
LIGHTRAG_GRAPH_STORAGE=Neo4JStorage

MILVUS_URI=rag_storage/milvus_lite.db
MILVUS_DB_NAME=
MILVUS_INDEX_TYPE=AUTOINDEX
MILVUS_METRIC_TYPE=COSINE

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password
NEO4J_DATABASE=neo4j
NEO4J_WORKSPACE=raganything

MILVUS_URI 指向本地 .db 文件时使用 Milvus Lite；后续升级到远程 Milvus 或 Zilliz 时，只需替换该 URI 和认证配置。Neo4j 需要本地或远程服务已经运行。

当前 MCP 只显式切换 LightRAG 的向量存储和图谱存储；KV 存储与文档状态存储仍保持默认本地 JSON。raganything_graph_stats 和 raganything_graph_search 是轻量文件检查工具，主要适用于默认 NetworkXStorage；切换到 Neo4JStorage 后，应以 RAG 查询和 Neo4j 自身查询作为图谱验证依据。

Embedding 入库阶段会对 chunks、entities 和 relationships 批量生成向量。公网 API 预检成功只说明单次小请求可用，不代表批量并发入库稳定。可以用下面的参数降低压力并放宽超时；后续切换到本地 Ollama embedding 时也复用同一组参数：

EMBEDDING_FUNC_MAX_ASYNC=2
EMBEDDING_BATCH_NUM=4
EMBEDDING_TIMEOUT_SECONDS=180

如果仍出现 Embedding func: Worker execution timeout，优先把 EMBEDDING_FUNC_MAX_ASYNC 降到 1；如果服务只是慢而非失败，再逐步增加 EMBEDDING_TIMEOUT_SECONDS。本地 Ollama 通常可以按机器能力再调大并发。

PARSER_TIMEOUT_SECONDS 默认是 120。解析 PDF 或图片时，如果 MinerU 超过该时间仍未完成，服务器会终止 MinerU 进程组并返回超时错误，避免解析任务在后台残留并持续占用资源。raganything_parse、raganything_ingest_file 和 raganything_ingest_folder 也支持传入 timeout_seconds 覆盖单次调用超时。

OpenClaw 等 stdio MCP 客户端处理 PDF 摄取时，应默认使用 raganything_ingest_file 的 wait_for_completion=false。推荐流程是：

1. 调用 raganything_ingest_file。

2. 保存返回的 job_id。

3. 向用户报告 job_id 和后台提交状态。

4. 停止当前 agent turn，除非用户明确要求等待、监控、入库后查询或验证完成。

这个后台作业由一个分离的单次 worker 进程执行，不依赖 OpenClaw 的单次 agent turn，也不依赖 stdio MCP server 的生命周期。即使客户端请求已经返回、agent turn 已结束，worker 仍会继续跑完摄取和入库流程。wait_for_completion=true 主要用于小文件或排错场景；大 PDF 可能会超过 MCP 请求超时，因此不适合把同步等待作为默认路径。

Agent polling behavior

OpenClaw 等 agent 默认应在后台入库提交后报告 job_id 并返回控制权，不要自动轮询。只有当用户明确要求 monitor、wait、ingest and query，或要求检查失败原因时，才调用 raganything_job_status(job_id) 继续跟踪任务。用户之后询问状态时，再使用保存的 job_id 查询。

不要把大 PDF 走成 raganything_parse(include_content=true) 再 raganything_insert_content_list 的流程。parse 适合调试解析结果；完整入库应直接使用 raganything_ingest_file。如果确实已有内容列表要插入，raganything_insert_content_list 也默认提交后台任务并返回 job_id；只有需要监控、等待或排错时才通过 raganything_job_status 查询。

同一工作目录一次只会有一个 ingest worker 运行。若当前任务仍在运行，请先等待它在 raganything_job_status 中变成 succeeded 或 failed，再提交下一次 ingest。

MinerU backend 默认使用 PARSER_BACKEND=pipeline，并默认关闭 MINERU_FORMULA=false 与 MINERU_TABLE=false，避免普通 CPU/虚拟机首次解析时误走 hybrid/vlm 高精度路径并下载大体积 VLM 模型。需要高精度解析时，可以在 .env 中设置 backend，或在单次 MCP 调用中传入 backend、model_source、formula、table 覆盖默认值。

MinerU 执行模式通过 MINERU_EXECUTION_MODE 控制：

• local：默认模式，使用本机 mineru CLI。

• api：使用 MinerU 官方精准解析 API。只需要配置 MINERU_API_KEY；MINERU_API_BASE_URL 默认是 https://mineru.net。服务会通过官方批量上传接口申请上传 URL、上传本地文件、轮询解析结果并下载 zip，再转换为本地 RAG-Anything 内容列表。

常用 API 模式配置：

MINERU_EXECUTION_MODE=api
MINERU_API_KEY=你的 MinerU API key
MINERU_API_BASE_URL=https://mineru.net
MINERU_API_TIMEOUT_SECONDS=1800
MINERU_API_POLL_INTERVAL_SECONDS=5
JOB_TIMEOUT_SECONDS=3600
TEXT_INGEST_TIMEOUT_SECONDS=1800
MULTIMODAL_TIMEOUT_SECONDS=

raganything_job_status 会保留任务真实状态和阶段，例如 status=running、stage=ingest 或 stage=processing。如果运行中已经检测到图谱存储文件，会额外返回 storage_progress.graph_stats，但不会把任务伪装成已完成。若后台任务超过 JOB_TIMEOUT_SECONDS 仍未返回，会标记为 failed 并写入 TimeoutError。TEXT_INGEST_TIMEOUT_SECONDS 是官方 LightRAG/RAG-Anything 插入阶段的慢任务告警阈值，超过后只会在 manifest 中记录 text_ingest_slow warning 并继续等待官方入库完成，不会取消 insert_content_list(process_multimodal=True)。如果历史 job 因旧的 text ingest timeout 被标成 resumable_failed，但本地 doc_status 与 chunk 存储已经证明官方入库完成，raganything_job_status 会把该 job 收敛为 succeeded。MULTIMODAL_TIMEOUT_SECONDS 默认为空，表示不单独限制多模态后处理；设置为正整数后，图片/表格/公式等多模态后处理超过该秒数会让本次入库明确失败，避免任务长期停在半完成状态。

模型拉取策略通过 MODEL_DOWNLOAD_POLICY 控制：

• auto：默认策略。允许高精度 backend 拉取所需模型；当 backend 是 hybrid* 或 vlm* 时，解析超时会至少扩展到 MODEL_DOWNLOAD_TIMEOUT_SECONDS，默认 1800 秒，避免首次模型准备被短解析超时误杀。

• never：禁止高精度 backend 触发可能的大模型下载；此时请使用 pipeline 或先手动准备模型。

• require-ready：要求高精度模型已存在于本地缓存，否则在解析前直接报错，适合生产环境避免业务请求中临时下载大模型。

raganything_parse、raganything_ingest_file 和 raganything_ingest_folder 支持 start_page 与 end_page 限制解析页码。MCP 参数使用用户习惯的 1-based 页码，例如 start_page=1,end_page=3 表示只解析第 1 到第 3 页；服务器内部会自动转换为 MinerU 使用的 0-based 页码。不传页码时默认解析整个文件。

工具

服务器会注册 13 个 MCP 工具：

• raganything_status：报告配置、存储路径、模型摘要以及可选的解析器可用性。

• raganything_config_info：返回当前生效的安全配置摘要。

• raganything_parse：将一个源文件解析为 RAG-Anything 内容块。

• raganything_ingest_file：默认提交文件解析和摄取后台任务，返回 job_id；OpenClaw stdio MCP 客户端做 PDF 摄取时应默认使用 wait_for_completion=false。传入 wait_for_completion=true 时同步等待完成，适合小文件或排错。

• raganything_ingest_folder：解析并摄取某个文件夹中的文件。

• raganything_insert_content_list：默认提交现有 RAG-Anything 内容列表的后台插入任务，返回 job_id；传入 wait_for_completion=true 时同步插入，适合小列表或排错。后台模式会拒绝过大的 content_list payload，此时应改用原始文件调用 raganything_ingest_file。

• raganything_job_status：根据 job_id 查看后台任务状态、阶段、结果或错误。

• raganything_list_jobs：列出最近的后台任务。

• raganything_query：查询已摄取的知识库。

• raganything_query_multimodal：使用多模态内容进行查询。

• raganything_graph_stats：统计图谱存储中的实体、关系、分块和文档数量。

• raganything_graph_search：按关键字搜索图谱存储载荷，默认省略向量字段；只有排查底层存储时才传入 include_vectors=true。

• raganything_graph_export：将图谱存储载荷导出为 JSON，保存到配置的工作目录中。

图谱工具会直接从 WORKING_DIR 读取 RAG-Anything 存储文件；它们适用于在不运行完整查询的情况下检查已摄取数据。

raganything_query 接受 response_mode：

• answer：仅返回生成的答案。

• context：仅返回检索到的上下文。

• both：返回检索到的上下文和生成的答案。

可选离线缓存

默认不包含 model_cache/ 和 tiktoken_cache/ 等离线缓存目录。如果你的部署需要这些目录，请自行将缓存目录复制到相应位置，并在启动服务器前将相关环境变量指向这些路径。

客户端示例

示例客户端配置文件位于 examples/：

• examples/openclaw.json

• examples/claude_code.md

请在连接客户端之前运行 raganything-mcp configure，以便服务器拥有可用的模型和存储设置。

冒烟测试

首先从你的 MCP 客户端检查服务器配置和连接：

1. 调用 raganything_status，并将 check_parser 设置为 false。

2. 如果模型设置看起来正确，调用 raganything_config_info。

3. 可以选择调用 raganything_status，并将 check_parser 设置为 true，以验证解析器可用性。

然后使用一个小型本地文件测试 RAG 路径：

1. 将一份简短文本、Markdown、PDF 或其他受支持的文件放入此项目目录。

2. 使用该文件路径调用 raganything_ingest_file，记录返回的 job_id。

3. 使用 raganything_job_status 轮询该 job_id，直到状态变为 succeeded；如果状态为 failed，查看返回的 error。如果还有一个 ingest 任务在跑，先等它结束再提交新的文件。

4. 调用 raganything_graph_stats，确认 chunks、entities 或 relationships 已增加。

5. 调用 raganything_query，提出一个关于该文件的简单问题。

6. 如有需要，将 response_mode 设置为 context 或 both，以检查检索到的上下文。