Skip to main content
Glama
RAGFlow Claude MCP Server

RAGFlow Claude MCP Server

by norandom

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

Установка

  1. Клонируйте:

    git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp
    cd ragflow-claude-desktop-local-mcp
  2. Установите:

    # On macOS, install DSPy first to dodge build issues:
    pip install git+https://github.com/stanfordnlp/dspy.git
    
    uv install
  3. Настройте: скопируйте образец и заполните свои данные RAGFlow.

    cp config.json.sample config.json

    Ключи:

    • RAGFLOW_BASE_URL: например, http://your-ragflow-server:9380

    • RAGFLOW_API_KEY: ваш API-ключ RAGFlow

    • RAGFLOW_DEFAULT_RERANK: модель переранжирования (по умолчанию rerank-multilingual-v3.0)

    • CF_ACCESS_CLIENT_ID (опционально): ID сервисного токена Cloudflare Zero Trust

    • CF_ACCESS_CLIENT_SECRET (опционально): секрет сервисного токена Cloudflare Zero Trust

    • DSPY_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.0

  • page (опционально, по умолчанию 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.

  1. Сделайте форк.

  2. git checkout -b feature/your-thing.

  3. Внесите изменения, напишите понятное сообщение коммита.

  4. Отправьте в свой форк.

  5. Откройте PR в main.

PR автоматически проверяются TruffleHog — не включайте ключи, токены или секреты. См. CONTRIBUTING.md для получения подробной информации.

Available Tools

8 tools
ragflow_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

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Integrates 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
      -
    • A
      license
      A
      quality
      F
      maintenance
      Connects 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.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables semantic retrieval and knowledge base management through the RAGFlow API, including dataset, document, chunk, chat, and graph operations.
      7
      MIT