RAGFlow Claude MCP Server
RAGFlow Claude MCP Server
Небольшой сервер Model Context Protocol (MCP), который подключает Claude Desktop (и другие MCP-клиенты) к экземпляру RAGFlow. Он предоставляет REST API RAGFlow в виде набора инструментов, чтобы LLM могла запрашивать базы знаний и извлекать фрагменты документов в свой контекст.
Это программное обеспечение для личного использования, которое я написал для своих собственных исследований и разработок. В нем есть ошибки, а код не идеален. Он работает так, как мне нужно.
Что он делает
Прямое извлечение: получает необработанные фрагменты документов с оценками сходства из эндпоинта
/retrievalв RAGFlow.Поиск по нескольким базам знаний (KB): один запрос может охватывать несколько баз знаний одновременно.
Углубление запроса с помощью DSPy: опциональное итеративное уточнение запроса (использует LLM для анализа промежуточных результатов и переписывания запроса).
~~Переранжирование~~ — в настоящее время не работает на стороне RAGFlow, см. Известные проблемы.
Настраиваемый контроль результатов:
page_size,similarity_threshold,top_k, пагинация.Фильтр документов: ограничение результатов одним документом внутри набора данных (нечеткое сопоставление имен).
Поиск набора данных по имени (без учета регистра, нечеткий) вместо ID.
Аутентификация Cloudflare Zero Trust, если ваш RAGFlow находится за ней.
Related MCP server: RAGBrain MCP
Установка
Клонируйте:
git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp cd ragflow-claude-desktop-local-mcpУстановите:
# On macOS, install DSPy first to dodge build issues: pip install git+https://github.com/stanfordnlp/dspy.git uv installНастройте: скопируйте образец и заполните свои данные RAGFlow.
cp config.json.sample config.jsonКлючи:
RAGFLOW_BASE_URL: например,http://your-ragflow-server:9380RAGFLOW_API_KEY: ваш API-ключ RAGFlowRAGFLOW_DEFAULT_RERANK: модель переранжирования (по умолчаниюrerank-multilingual-v3.0)CF_ACCESS_CLIENT_ID(опционально): ID сервисного токена Cloudflare Zero TrustCF_ACCESS_CLIENT_SECRET(опционально): секрет сервисного токена Cloudflare Zero TrustDSPY_MODEL: модель DSPy LM (по умолчаниюopenai/gpt-4o-mini)OPENAI_API_KEY: необходимо для углубления DSPy
Cloudflare Zero Trust
Если ваш RAGFlow находится за Cloudflare Zero Trust, получите сервисный токен на панели управления и добавьте его в config.json:
{
"CF_ACCESS_CLIENT_ID": "your-client-id.access",
"CF_ACCESS_CLIENT_SECRET": "your-client-secret"
}Когда оба параметра установлены, каждый API-запрос отправляется с заголовками CF-Access-Client-Id и CF-Access-Client-Secret. Изменение кода не требуется.
Конфигурация Claude Desktop
{
"mcpServers": {
"ragflow": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/ragflow-claude-desktop-local-mcp",
"ragflow-claude-mcp"
]
}
}
}Инструменты
ragflow_retrieval_by_name (тот, который я использую чаще всего)
Извлечение фрагментов из одного или нескольких наборов данных по имени. Возвращает необработанные фрагменты с оценками сходства.
Параметры:
dataset_names(обязательно) — список, например,["BASF", "Quant Literature"]query(обязательно)document_name(опционально) — ограничение одним документом; нечеткое сопоставлениеtop_k(опционально, по умолчанию 1024) — векторные кандидатыsimilarity_threshold(опционально, по умолчанию 0.2) — 0.0–1.0page(опционально, по умолчанию 1)page_size(опционально, по умолчанию 10)use_rerank(опционально, по умолчанию false) — в настоящее время не работает, см. Известные проблемыdeepening_level(опционально, по умолчанию 0) — уточнение DSPy, 0–3
ragflow_retrieval
Та же структура, но принимает dataset_ids: List[str] вместо имен.
Поиск по нескольким базам знаний
Вы можете искать по нескольким базам знаний за один вызов. Убедитесь, что они используют одну и ту же модель эмбеддингов — смешивание несовместимых эмбеддингов снизит точность оценок релевантности.
Use ragflow_retrieval_by_name with dataset_names ["Finance Reports", "Legal Documents"] and query "Summarize the key financial risks and compliance requirements for new market entry."ragflow_list_datasets
Выводит список всех баз знаний в вашем экземпляре RAGFlow. Параметры не требуются. Внутренне проходит по всем страницам.
ragflow_list_documents
Выводит список документов в наборе данных. Проходит по всем страницам.
dataset_id(обязательно)
ragflow_get_chunks
Возвращает фрагменты (со ссылками) для одного документа.
dataset_id(обязательно)document_id(обязательно)
ragflow_list_sessions
Показывает активные сессии чата для каждого набора данных. Параметры не требуются.
ragflow_list_documents_by_name
Выводит список документов в наборе данных, поиск по имени.
dataset_name(обязательно)
ragflow_reset_session
Завершает сессию чата для набора данных.
dataset_id(обязательно)
Настройка извлечения
Инструменты извлечения имеют три настройки:
page_size— количество фрагментов на страницу (по умолчанию 10).similarity_threshold— отбрасывает фрагменты ниже этой оценки (по умолчанию 0.2).top_k— размер пула для векторного поиска перед фильтрацией (по умолчанию 1024).
Некоторые начальные значения, которые работают у меня:
Широкий охват:
page_size=15,similarity_threshold=0.15.Высокая точность:
page_size=5,similarity_threshold=0.4.Глубокое исследование:
page_size=20,similarity_threshold=0.1,deepening_level=1.Сложные запросы:
deepening_level=2.Скорость: оставьте
deepening_level=0и пропустите переранжирование.
Примеры
Базовое извлечение по имени:
Use ragflow_retrieval_by_name with dataset_names ["BASF"] and query "What is BASF's latest income statement? Revenue, operating income, net income, and other key figures."Ограничение одним документом:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], document_name "annual_report_2023", and query "What were the key financial highlights for 2023?"Имена документов сопоставляются нечетко — "annual" найдет annual_report_2023.pdf и annual_report_2024.pdf. Если совпадений несколько, сервер выбирает самый последний и перечисляет альтернативы в метаданных ответа.
Углубление DSPy для сложного запроса:
Use ragflow_retrieval_by_name with dataset_names ["Quant Literature"], query "what is a volatility clock", deepening_level 2.Многостраничный поиск:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], query "BASF business segments", page_size 10, page 2.Список доступных данных:
Use ragflow_list_datasets.Use ragflow_list_documents_by_name with dataset_name "BASF".Получение конкретных фрагментов:
Use ragflow_get_chunks with dataset_id "43066ee0599411f089787a39c10de57b" and document_id "d74a1c105a3311f09fc94a0fcd8b7722".Большие промпты
Некоторые примеры того, как я использую это в Claude Desktop.
Финансовый глубокий анализ:
Help me analyse BASF's recent financials.
1. Use ragflow_retrieval_by_name to search ["BASF"] for the latest income statement
(revenue, operating income, net income). Use page_size 15,
similarity_threshold 0.15, deepening_level 1.
2. Then run ragflow_retrieval_by_name again for the cash flow statement,
page_size 10, similarity_threshold 0.2.
3. Finally look for year-over-year changes with page_size 12,
similarity_threshold 0.18.Многоязычное исследование:
Use ragflow_retrieval_by_name with dataset_names ["BASF"],
query "Was sind die wichtigsten Geschäftsbereiche von BASF?",
deepening_level 2.DSPy определяет язык запроса и уточняет его соответствующим образом. Я использовал это для немецких, английских и смешанных запросов. Это работает, пока базовые документы содержат контент на этих языках.
Исследование с фильтрацией по документу:
1. Use ragflow_list_documents_by_name with dataset_name "BASF" to see what's in there.
2. Use ragflow_retrieval_by_name with dataset_names ["BASF"],
document_name "sustainability_report", query "carbon neutrality goals",
page_size 15, deepening_level 1.
3. Follow up with document_name "annual_report_2023" and
query "environmental investments".Запрос по нескольким базам знаний:
Use ragflow_retrieval_by_name with dataset_names ["BASF", "Industry Reports"],
query "chemical industry sustainability benchmarks",
page_size 12, deepening_level 1.Как работает углубление DSPy
deepening_level запускает цикл уточнения на основе LLM поверх извлечения:
0: без углубления (по умолчанию).
1: один проход уточнения.
2: два прохода с анализом пробелов.
3: три и более проходов плюс объединение результатов.
Каждый проход: выполнение поиска, обобщение лучших результатов, вопрос к LLM о том, чего не хватает, генерация нового запроса, выполнение поиска. Метаданные ответа включают исходный запрос, каждый уточненный запрос и обоснование на каждом шаге.
DSPy требует:
DSPY_MODEL—openai/gpt-4o-miniработает отличноOPENAI_API_KEY
Переранжирование (в настоящее время не работает)
Когда эта функция работает, переранжирование заменяет косинусную оценку вектора на оценку модели переранжирования (по моему опыту, релевантность обычно на 10–30% выше). В RAGFlow сейчас есть известная ошибка, из-за которой use_rerank=true вызывает:
UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol
Поэтому оставьте use_rerank=false, пока проблема не будет исправлена. Стандартное векторное извлечение работает нормально.
Как работает поиск набора данных
Поиск по имени без учета регистра.
Нечеткое сопоставление для частичных имен.
Наборы данных кэшируются для поиска по имени; промахи кэша вызывают обновление.
Если поиск не удался, ошибка включает доступные имена наборов данных, чтобы вы знали, что было на самом деле.
Сопоставление документов
Когда вы передаете document_name:
Точное совпадение выигрывает, затем "начинается с", затем "содержит", затем частичное.
При равенстве выигрывает более недавно обновленный документ.
Имена, содержащие
2024,2023,latest,currentилиnew, получают небольшой бонус к оценке.Все совпадения возвращаются в метаданных ответа, чтобы вы могли повторить запрос с более конкретным именем.
Обработка ошибок
Разумные сообщения об ошибках для: ошибок API, отсутствующих наборов данных, недоступного RAGFlow, разорванных сессий, неверного ввода и проблем с конфигурацией. Чувствительные значения скрываются в логах.
Переменные окружения
RAGFLOW_BASE_URL— переопределяет файл конфигурации. Значение по умолчанию в коде:http://192.168.122.93:9380(мой локальный экземпляр).RAGFLOW_API_KEY— обязательно.
Разработка
Запуск сервера напрямую:
uv run ragflow-claude-mcpОн слушает stdio, как и другие MCP-серверы.
Зависимости для разработки:
uv install --extra devЭто установит pytest + плагины asyncio/mock/cov.
Тесты:
uv run pytest
uv run pytest --cov=src --cov-report=html --cov-report=term
uv run pytest tests/test_server.py
uv run pytest -vПокрытие составляет около 44%, 22/23 тестов проходят (один пропущен из-за периодического сбоя CI). Тесты охватывают инициализацию сервера, интеграцию API RAGFlow, углубление DSPy, ветки конфигурации OpenAI/OpenRouter и загрузку конфигурации.
Примечания по реализации
API извлечения — это единственная поверхность RAGFlow, на которую полагается сервер. Никаких зависимостей от помощника/чата, никакой конфигурации промптов на стороне сервера — только фрагменты. Проще для понимания, проще для отладки.
Устранение неполадок
"Dataset not found": запустите
ragflow_list_datasets, чтобы увидеть, что там есть на самом деле.Ошибки подключения: дважды проверьте
RAGFLOW_BASE_URLиRAGFLOW_API_KEY.Сервер не запускается: завершилась ли установка
uv install?Нужны необработанные фрагменты: используйте
ragflow_retrieval_by_name/ragflow_retrieval.Зависшая сессия:
ragflow_list_sessions, затемragflow_reset_session.Ошибки 403 от Cloudflare: подтвердите, что
CF_ACCESS_CLIENT_ID/CF_ACCESS_CLIENT_SECRETсоответствуют активному сервисному токену в приложении Zero Trust.
Известные проблемы
Переранжирование не работает на стороне сервера
use_rerank=true выдает ошибку UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol. Это дефект на стороне RAGFlow. Обходной путь: оставьте эту функцию выключенной. Я слежу за репозиторием RAGFlow в ожидании исправления.
Участие в разработке
Только через PR — ветка main защищена. Коммиты должны быть подписаны SSH.
Сделайте форк.
git checkout -b feature/your-thing.Внесите изменения, напишите понятное сообщение коммита.
Отправьте в свой форк.
Откройте PR в
main.
PR автоматически проверяются TruffleHog — не включайте ключи, токены или секреты. См. CONTRIBUTING.md для получения подробной информации.
Available Tools
8 toolsragflow_get_chunksC
Get chunks with references from a specific document
Inputs: dataset_id (required), document_id (required).
ragflow_list_datasetsA
List all available datasets/knowledge bases in RAGFlow
Inputs: no named parameters.
ragflow_list_documentsC
List documents in a specific dataset
Inputs: dataset_id (required).
ragflow_list_documents_by_nameC
List documents in a dataset by dataset name
Inputs: dataset_name (required).
ragflow_list_sessionsB
List active chat sessions for all datasets
Inputs: no named parameters.
ragflow_reset_sessionB
Reset/clear the chat session for a specific dataset
Inputs: dataset_id (required).
ragflow_retrievalB
Retrieve document chunks directly from RAGFlow datasets using the retrieval API. Returns raw chunks with similarity scores.
Inputs: query (required), dataset_ids (required), page, top_k, +5 more.
ragflow_retrieval_by_nameB
Retrieve document chunks by dataset names using the retrieval API. Returns raw chunks with similarity scores.
Inputs: query (required), dataset_names (required), page, top_k, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes, but ragflow_list_documents and ragflow_retrieval each have an alternative by-name variant, which could cause confusion if descriptions are not heeded. However, descriptions clarify the difference between ID-based and name-based operations, keeping overlap minimal.
All tools follow a consistent verb_noun pattern with snake_case and the 'ragflow_' prefix. Variations like '_by_name' are systematic and predictable, enhancing readability for agents.
With 8 tools, the set is well-scoped for a knowledge base retrieval server. Each tool serves a clear function, and the count is neither too sparse nor overwhelming for the intended purpose.
The tool surface covers listing datasets, listing documents, retrieving chunks, and managing chat sessions. It lacks create/update/delete operations, but given the likely read-heavy focus of the server, these gaps are acceptable and do not impede the primary retrieval workflow.
Maintenance
Related MCP Connectors
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Ask your own documents and get answers that cite the source passage. Workspace knowledge bases over MCP for Cursor, Claude and any MCP client.
Related MCP Servers
- FlicenseAqualityDmaintenanceIntegrates R2R (Retrieval-Augmented Generation) with Claude Desktop, enabling semantic search across knowledge bases and RAG-based question answering with support for vector, graph, web, and document search.2-
- AlicenseAqualityFmaintenanceConnects Claude Desktop to a RAGBrain knowledge base to enable semantic search, document retrieval, and namespace management. It allows users to browse collections, discover documents by topic, and access full text content through natural language.5MIT
- AlicenseAqualityDmaintenanceProvides semantic search capabilities by connecting Claude Desktop to a Cloudflare Workers backend powered by Vectorize. It enables natural language querying of knowledge bases using vector similarity and edge-based embedding generation.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables semantic retrieval and knowledge base management through the RAGFlow API, including dataset, document, chunk, chat, and graph operations.7MIT